Skip to main content
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:
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.
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:
It requires network access while starting. The default command runs mcp-use dev, which serves the default export and built-in inspector.