> ## 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 -> MCP

> Generate MCP tools from an OpenAPI document

`MCPServer.fromOpenAPI()` creates an MCP server from a parsed OpenAPI document. Each included OpenAPI operation is registered as an MCP tool that calls the matching HTTP endpoint.

<Tip>
  We do not recommend mapping a production API directly to MCP without review. LLMs usually perform better with a deliberately crafted MCP server: focused tools, clear names, model-friendly descriptions, and workflows that match the tasks users actually ask for.
</Tip>

## Basic Usage

Load or import an OpenAPI document, then pass it to `MCPServer.fromOpenAPI()`:

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

const response = await fetch("https://api.example.com/openapi.json");

if (!response.ok) {
  throw new Error(`Failed to fetch OpenAPI spec: ${response.status}`);
}

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

const server = MCPServer.fromOpenAPI({
  spec,
  baseUrl: "https://api.example.com",
});

await server.listen(3000);
```

The generated server uses the OpenAPI document for:

* Server name and version, unless you override them
* Tool names, based on `operationId` when available
* Tool descriptions, from `summary`, `description`, and the HTTP route
* Input schemas, from parameters and JSON request bodies
* HTTP method, path, query string, headers, and request body

## When to Use It

`fromOpenAPI()` is useful when you want to quickly expose an existing HTTP API to an MCP client:

* Prototyping an MCP integration before designing custom tools
* Wrapping a small internal API for trusted users
* Testing whether an API's operations are useful in an LLM workflow
* Bootstrapping a hand-crafted MCP server from an existing OpenAPI spec

For user-facing or high-volume servers, prefer a custom MCP server once you know the workflow. A good custom server often combines multiple HTTP calls into one tool, hides API-specific fields the model should not reason about, adds better descriptions, and returns only the response shape the model needs.

## Authentication and Headers

`fromOpenAPI()` supports two simple upstream authentication patterns:

* Bearer token auth
* Static header auth, such as an API key header

Read secrets from environment variables instead of hard-coding them:

```typescript theme={null}
const server = MCPServer.fromOpenAPI({
  spec,
  baseUrl: "https://api.example.com",
  auth: {
    type: "bearer",
    token: process.env.EXAMPLE_API_TOKEN,
  },
});
```

For API key headers:

```typescript theme={null}
const server = MCPServer.fromOpenAPI({
  spec,
  baseUrl: "https://api.example.com",
  auth: {
    type: "header",
    name: "x-api-key",
    value: process.env.EXAMPLE_API_KEY,
  },
});
```

Use `headers` for static headers that should be sent with every upstream request:

```typescript theme={null}
const server = MCPServer.fromOpenAPI({
  spec,
  baseUrl: "https://api.example.com",
  headers: {
    "User-Agent": "my-mcp-server/1.0",
    Accept: "application/json",
  },
});
```

<Note>
  The `auth` and `headers` options authenticate requests from your MCP server to the upstream API. They do not add authentication to the MCP server itself. To protect the MCP endpoint, configure server authentication separately.
</Note>

## Request and Response Mapping

Generated tools flatten OpenAPI parameters into a single input object:

* `path` parameters become required top-level fields
* `query` parameters become optional or required top-level fields
* `header` parameters become top-level fields and are sent as HTTP headers
* `cookie` parameters are ignored
* JSON request bodies become a `body` field

For example, an operation like `GET /users/{userId}/projects?limit=10` becomes a tool with `userId` and `limit` inputs.

JSON responses are returned with the `object()` response helper. Non-JSON responses are returned as text. If the upstream API returns a non-2xx response, the generated tool returns an MCP error response containing the upstream response text.

## Naming and Descriptions

Tool quality depends heavily on the OpenAPI document. Before exposing generated tools to users, review the spec for:

* Clear `operationId` values
* Human-readable `summary` and `description` fields
* Helpful parameter descriptions
* Small, accurate schemas
* Tags that match useful task areas

If the generated names or descriptions feel too API-shaped, that is usually a sign to write custom tools. For example, a custom `search_customer_orders` tool may be better than separate generated tools for `listCustomers`, `getCustomer`, `listOrders`, and `getOrder`.

## Options

```typescript theme={null}
type FromOpenAPIOptions = {
  spec: OpenAPIDocument;
  baseUrl?: string;
  name?: string;
  version?: string;
  auth?: OpenAPIAuth;
  headers?: Record<string, string>;
  tags?: string[];
  exclude?: OpenAPIExcludeRule[];
  fetch?: typeof fetch;
};
```

| Option    | Description                                                            |
| --------- | ---------------------------------------------------------------------- |
| `spec`    | Parsed OpenAPI document. This is required.                             |
| `baseUrl` | Upstream API base URL. Defaults to `spec.servers[0].url` when present. |
| `name`    | MCP server name. Defaults to `spec.info.title`.                        |
| `version` | MCP server version. Defaults to `spec.info.version` or `1.0.0`.        |
| `auth`    | Bearer token or static header auth for upstream API requests.          |
| `headers` | Static headers sent with every upstream API request.                   |
| `tags`    | Include only operations with one of these OpenAPI tags.                |
| `exclude` | Exclude operations by operation ID, path, method, or tag.              |
| `fetch`   | Custom fetch implementation, useful for tests or custom transports.    |

## Limitations

`fromOpenAPI()` is intentionally simple. It currently focuses on straightforward REST-style APIs with JSON request and response bodies.

* It does not design model-friendly workflows for you
* It does not add MCP server authentication
* It does not support cookie parameters
* It only maps JSON request bodies into tool input
* It does not automatically bundle remote `$ref` values outside the loaded document

If you run into these limits, use the generated server as a reference and move the important operations into hand-written `server.tool()` definitions.

## Example

<Card title="OpenAPI Server Example" icon="github" href="https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/features/openapi">
  Complete runnable example that generates MCP tools from the National Weather Service OpenAPI document.
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Tools" icon="wrench" href="/typescript/server/tools">
    Learn how to create hand-crafted MCP tools with Zod schemas and custom handlers.
  </Card>

  <Card title="Examples" icon="folder-code" href="/typescript/server/examples">
    Browse runnable server examples, including the OpenAPI feature example.
  </Card>
</CardGroup>