Skip to main content
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.
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.

​
Basic Usage

Load or import an OpenAPI document, then pass it to MCPServer.fromOpenAPI(): 
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: 
const server = MCPServer.fromOpenAPI({
  spec,
  baseUrl: "https://api.example.com",
  auth: {
    type: "bearer",
    token: process.env.EXAMPLE_API_TOKEN,
  },
});
For API key headers: 
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: 
const server = MCPServer.fromOpenAPI({
  spec,
  baseUrl: "https://api.example.com",
  headers: {
    "User-Agent": "my-mcp-server/1.0",
    Accept: "application/json",
  },
});
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.

​
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

type FromOpenAPIOptions = {
  spec: OpenAPIDocument;
  baseUrl?: string;
  name?: string;
  version?: string;
  auth?: OpenAPIAuth;
  headers?: Record<string, string>;
  tags?: string[];
  exclude?: OpenAPIExcludeRule[];
  fetch?: typeof fetch;
};
OptionDescription
specParsed OpenAPI document. This is required.
baseUrlUpstream API base URL. Defaults to spec.servers[0].url when present.
nameMCP server name. Defaults to spec.info.title.
versionMCP server version. Defaults to spec.info.version or 1.0.0.
authBearer token or static header auth for upstream API requests.
headersStatic headers sent with every upstream API request.
tagsInclude only operations with one of these OpenAPI tags.
excludeExclude operations by operation ID, path, method, or tag.
fetchCustom 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

OpenAPI Server Example

Complete runnable example that generates MCP tools from the National Weather Service OpenAPI document.

​
Next Steps

Tools

Learn how to create hand-crafted MCP tools with Zod schemas and custom handlers.

Examples

Browse runnable server examples, including the OpenAPI feature example.