---
title: "OpenAPI"
description: "Generate MCP tools from an OpenAPI document"
icon: "file-code"
---

`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
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
const server = MCPServer.fromOpenAPI({
  spec,
  baseUrl: "https://api.example.com",
  auth: {
    type: "bearer",
    token: process.env.EXAMPLE_API_TOKEN,
  },
});
```

For API key headers:

```typescript
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
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
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>
