> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI

> Generate MCP tools from a bundled OpenAPI document.

`MCPServer.fromOpenAPI()` registers each included OpenAPI operation as a tool
that calls the matching HTTP endpoint.

## Create the server

Pass a parsed, bundled OpenAPI 3.x document and default-export the server:

```typescript theme={null}
import { MCPServer, type OpenAPIDocument } from "mcp-use";

const response = await fetch("https://api.example.com/openapi.json");
if (!response.ok) {
  throw new Error(`Failed to load OpenAPI: ${response.status}`);
}

const spec = (await response.json()) as OpenAPIDocument;

const server = MCPServer.fromOpenAPI({
  spec,
  baseUrl: "https://api.example.com",
  headers: { "x-client": "inventory-mcp" },
  auth: {
    type: "bearer",
    token: process.env.INVENTORY_TOKEN,
  },
});

export default server;
```

`baseUrl` overrides `spec.servers[0].url`. One of them is required when the
document contains operations. The loader does not fetch external `$ref`
targets, so bundle external references into local `#/...` references before
creating the server.

## Select operations

`tags` includes operations that have at least one exact matching tag.
`exclude` is applied afterward. All fields in one exclusion rule are ANDed;
the `tags` field matches when the operation has any listed tag.

```typescript theme={null}
const server = MCPServer.fromOpenAPI({
  spec,
  tags: ["public", "inventory"],
  exclude: [
    { operationId: /^admin/, method: "POST" },
    { path: "/internal/status" },
  ],
});
```

String `operationId` and `path` matches are exact. Use a `RegExp` for pattern
matching. Methods are case-insensitive.

## Understand generated inputs

Path, query, and header parameters become tool inputs. Cookie parameters are
ignored. Operation-level parameters replace path-level parameters with the
same location and name.

Name collisions are resolved deterministically:

* Parameters with the same name receive location suffixes such as
  `id_path` and `id_query`.
* A parameter named `body` is also location-suffixed when a JSON request body
  exists.
* Further collisions receive numeric suffixes such as `_2`.

Only JSON-compatible request bodies are exposed, under the `body` input.
Supported media types are `application/json`, `application/*+json`, and
specific media types containing `+json`. Other body encodings are not sent.

Array query values are serialized as repeated keys:
`?tag=one&tag=two`. OpenAPI query serialization styles such as comma-separated
or deep-object encoding are not interpreted.

## Understand tool names

An operation's `operationId` is preferred. Otherwise the method and path form a
fallback such as `get_reports_id`. Names are trimmed, unsupported characters
become underscores, repeated underscores collapse, and the result is capped at
64 characters. Collisions receive `_2`, `_3`, and later suffixes while
remaining within the cap.

## Understand results and errors

Generated tools return raw MCP results:

* Successful JSON becomes a JSON text block plus the parsed value in
  `structuredContent`.
* Successful text and invalid JSON bodies become a text block.
* Non-success HTTP responses become `{ isError: true, content: [...] }` with
  the upstream response text.

This mapping does not use response helpers and does not derive an
`outputSchema` from OpenAPI response definitions.

## Run the maintained example

The repository example loads a focused subset of the National Weather Service
document:

```bash theme={null}
cd libraries/typescript/packages/server/examples/openapi
pnpm dev
```

It requires network access while starting. The default command runs
`mcp-use dev`, which serves the default export and built-in inspector.