fromOpenAPI() (fastmcp/openapi) converts an OpenAPI 3.x document into a FastMCP server, turning each operation into a tool.
- Basic Usage
- Choosing which operations become tools
- GET → resources
- Structured output
- Query and form-body serialization
- Path parameter serialization
- Options
- Authentication
- Adding to an existing server
- Known limitations
import { fromOpenAPI } from "fastmcp/openapi";
const server = await fromOpenAPI({
spec: "https://petstore3.swagger.io/api/v3/openapi.json",
include: (operation) => operation.tags.includes("pet"),
});
await server.start({ transportType: "stdio" });spec accepts a URL, a local file path, or an already-parsed OpenAPI document (JSON or YAML). Passing a URL or file path — rather than an object you fetched and parsed yourself — is what lets external $refs (multi-file specs) and a relative servers[0].url resolve correctly, since both are resolved relative to that value.
Path Item $refs are supported too: when multiple paths share a definition, each remains a separate tool or resource at its own path.
Each operation uses the first server in its nearest non-empty servers array: operation, then path, then document. Server variables use their defaults, and relative URLs resolve against the spec URL. An explicit baseUrl overrides this selection for every generated tool or resource.
Tool inputs combine path, query, header, cookie, and body fields. If a parameter name is shared across locations or with a body property, it becomes {name}__{location}; body properties keep their names. If that generated alias is already occupied, _2, _3, and so on are appended until it is unique. These aliases only affect MCP input names; HTTP requests still use the original parameter and body names. Header parameters named Accept, Content-Type or Authorization are ignored, as the OpenAPI specification requires, so they never become tool inputs; set those headers through the headers option.
A top-level parameter or flattened body property named __proto__ also receives an alias, because the schema validator does not validate that literal property name. For example, a path parameter becomes __proto____path and a body property becomes __proto____body; occupied aliases receive the same numeric suffixes. The HTTP field name remains __proto__. This does not rename properties inside nested or whole-body schemas.
Turning every operation in a large spec into a tool produces a tool list most MCP clients can't work with well. There is no way to make this fully automatic, so fromOpenAPI asks you to choose:
const server = await fromOpenAPI({
spec: "https://api.example.com/openapi.json",
include: (operation) => operation.tags.includes("orders"),
exclude: (operation) => operation.operationId === "deleteAllOrders",
});include/exclude receive an OperationSummary ({ deprecated, method, operationId, path, tags }). Deprecated operations are excluded by default.
If neither include/exclude nor maxTools is given and the spec still produces more than 40 operations, fromOpenAPI throws instead of silently generating a wall of tools. Pass maxTools to raise that limit explicitly once you've decided that's really what you want.
Pass resources: true to map an eligible GET operation to an MCP resource (no parameters) or resource template (path and/or query parameters) instead of a tool:
const server = await fromOpenAPI({
spec: "https://petstore3.swagger.io/api/v3/openapi.json",
include: (operation) => operation.tags.includes("pet"),
resources: true,
});getPetById (GET /pet/{petId}) becomes a resource template at openapi://getPetById/pet/{petId}, readable via client.readResource({ uri: "openapi://getPetById/pet/10" }). A GET with no parameters at all becomes a static resource.
A GET stays a tool instead — even with resources: true — when:
- it has any
headerorcookieparameter (these can't be expressed in a resource URI, and resource reads have no per-call side channel for them), or - any of its path/query parameters is array-typed, including component schema references and nullable arrays (OpenAPI's array query serialization and RFC 6570's don't match), or
- any of its path/query parameters is object-typed, including component schema references and nullable objects (the URI template parser does not preserve the object shape needed for OpenAPI serialization).
This means a "get by ID" style endpoint typically becomes a resource template, while a "search/filter" endpoint with array- or object-valued query parameters typically stays a tool — which tends to match how each is actually used.
There's no per-operation override for this — an eligible GET always maps to a resource when resources: true; use exclude if you want a specific one to stay a tool instead of being generated at all.
Eligibility doesn't check the response's own content type, only the request shape. A GET returning binary data (an image, a PDF, ...) can still become a resource, and its response is read as text, not as the binary-safe blob a resource can also return — corrupting non-text bytes. If your spec has binary-returning GETs you want as resources, use exclude to keep them as tools instead until this is addressed.
When an operation declares a 2xx application/json response schema, its tool is given an outputSchema, and a successful call returns structuredContent (the parsed response object) instead of just a text blob — so an agent can consume typed fields directly rather than parsing JSON out of a string.
The response is checked against the advertised schema before being returned as structured content. When a tool has an outputSchema but the response doesn't match, isn't a JSON object, is served as text/plain, or has an empty body, the call returns a tool error (isError: true) containing the response text. This keeps the response visible to clients that validate calls against the advertised schema. Tools without an outputSchema keep returning plain-text successes; for example, an array-typed response schema is never wired to outputSchema in the first place.
An operation whose response schema is unusually large (more than 50 transitively-referenced component schemas — real for some "core" resource objects in large APIs) doesn't get outputSchema wired at all, both to keep tools/list fast and because a schema that large has limited practical value as structured output anyway.
Query parameters are serialized according to their declared style:
deepObject(e.g. Stripe'screated[gte]=...,expand[]=...filters) expands as bracket-notation pairs.spaceDelimited/pipeDelimitedarray values join into a single space- or pipe-separated value.form(the default when no style is declared) uses repeated keys for arrays —tag=a&tag=b— and property pairs for objects —R=100&G=200. Withexplode: false, arrays use a single comma-separated value, such asfields=id%2Cname(decoded value:id,name), and objects use alternating keys and values, such ascolor=R%2C100%2CG%2C200(decoded value:R,100,G,200). Values are URL-encoded; empty form-style arrays and objects are omitted.
Query parameters with allowReserved: true preserve query-safe reserved characters such as /, :, ?, and ,, plus existing percent-encoded triples (%2F stays %2F). Raw []#&=+ remain encoded to preserve the query structure and values; HTTP(S) URL serialization also encodes apostrophes. Other unsafe characters and Unicode are percent-encoded. Parameter names and query parameters with allowReserved: false or no flag keep their existing encoding.
For form-style query arrays and objects, explode defaults to true. Form-body encoding is unchanged by this flag.
With explode: false, commas inside individual array items or object keys/values are not escaped separately from the separators. For example, ["x,y", "z"] is sent as fields=x%2Cy%2Cz; a server that URL-decodes and then splits on commas cannot distinguish the comma inside the first item from a separator.
Form-style query objects support scalar property values; nested objects/arrays require deepObject serialization. Object-valued spaceDelimited/pipeDelimited queries, headers, and cookies are still sent as the literal string "[object Object]" (percent-encoded for form-style cookies).
Form-style cookie values (the default) are percent-encoded, leaving only letters, digits and -._~ as they are, so a value such as a; b=c is sent as a%3B%20b%3Dc and cannot add a cookie of its own. With OpenAPI 3.2 style: cookie the value is sent as given, already escaped by the caller, and a value holding ; or , is refused. Array items are encoded, or checked, one at a time and joined with commas.
Request bodies get the same bracket-notation treatment for nested objects/arrays (e.g. Stripe's metadata[key]=value) when form-urlencoded.
Required flattened JSON request bodies are sent as {} when no body properties are supplied. A required application/json body without a schema also sends {}. Omitted optional bodies remain absent.
Flat object path parameters support style: simple, including the path default when style is omitted. With { R: 100, G: 200, B: 150 }, explode: false (the default) produces R,100,G,200,B,150; explode: true produces R=100,G=200,B=150.
Each property key and scalar value is percent-encoded separately before adding the comma and equals-sign separators. For example, { "x,y": "a/b=c" } becomes x%2Cy,a%2Fb%3Dc, or x%2Cy=a%2Fb%3Dc when exploded. Empty objects expand to an empty path value.
Simple-style arrays also encode each item separately, then join them with commas, for either explode value. For example, ["blue,green", "red/white"] becomes blue%2Cgreen,red%2Fwhite, preserving the difference between a comma inside an item and a separator. Empty arrays expand to an empty path value. Scalar path parameters keep their existing encoding.
Nested object/array properties and other path styles (such as matrix and label) remain unsupported: these objects are still sent as the literal string "[object Object]".
| Option | Type | Description |
|---|---|---|
spec |
string | object |
Required. A URL, file path, or parsed OpenAPI document. |
name |
string |
Name for a newly-created server. Defaults to the spec's info.title, or "OpenAPI Server". |
version |
`${number}.${number}.${number}` |
Version for a newly-created server. Defaults to "1.0.0". |
server |
FastMCP |
Register the generated tools onto an existing server instead of creating one. |
include |
(operation: OperationSummary) => boolean |
Only keep matching operations. |
exclude |
(operation: OperationSummary) => boolean |
Drop matching operations, applied after include. |
maxTools |
number |
Hard cap; throws if the selected operation count exceeds it. |
mcpNames |
Record<string, string> |
Override the generated tool name for a given operationId. |
resources |
boolean |
Map eligible GETs to resources/resource templates instead of tools. Default false. |
baseUrl |
string |
Overrides the resolved servers[0].url. |
headers |
Record<string, string> | (() => Record<string, string>) |
Static or dynamically-resolved headers sent with every generated tool call. |
fetch |
typeof fetch |
HTTP client used to execute tool calls. Defaults to the global fetch. |
Most APIs need an API key or bearer token. Use headers:
const server = await fromOpenAPI({
spec: "https://api.example.com/openapi.json",
headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
});Pass a function instead of a plain object if the token needs to be refreshed per call.
Pass server to register the generated tools onto a server you've already created, alongside hand-written tools:
const server = new FastMCP({ name: "My Server", version: "1.0.0" });
server.addTool({ name: "customTool", execute: async () => "..." });
await fromOpenAPI({ spec: "https://api.example.com/openapi.json", server });This scope is deliberately kept tight:
- Tools by default. Every operation becomes a tool unless you opt into
resources: true, and even then only an eligibleGETis affected. application/jsonandapplication/x-www-form-urlencodedrequest bodies. Other content types (multipart/form-data,application/json-patch+json,application/octet-stream, ...) are skipped, not silently turned into a tool with no way to carry its payload —fromOpenAPIlogs oneconsole.warnlisting every operation it skipped this way.- An array-of-objects form-body property bracket-expands under
key[](not indexedkey[0][...]) — see Query and form-body serialization. - OpenAPI 3.x only. Swagger 2.0 documents are rejected with a clear error.
- A very large response schema doesn't get
outputSchemawired — see Structured output. - No CLI.
fromOpenAPIis a programmatic API; there is nofastmcp openapi <spec>command yet.