Openapi MCP

What @kaisers-io/openapi-mcp does

@kaisers-io/openapi-mcp lets an MCP-compatible agent call an HTTP API through its OpenAPI description. Each permitted operation can become an MCP tool, so an API can be connected without writing a custom integration or generating source code. The description may come from a remote URL or a local file, and the server runs on the agent host.

The default exposure is read-only: GET, HEAD, and QUERY operations are available until additional methods are explicitly allowed. Access can be narrowed or expanded with selectors based on HTTP method, path, operation ID, tag, or generated tool name. Deny rules take precedence over allow rules.

How it works

The host starts the server from its MCP configuration. The server reads the selected OpenAPI description, turns permitted operations into tools, and sends requests to the API when the agent calls them. Before sending a request, it checks arguments against the operation schema and rejects fields the operation does not define. Responses are also checked when the description provides a usable response schema.

Credentials can be supplied through named environment variables or protected files. Secret values are kept out of tool definitions and redacted from results, errors, and logs. For a remote description, specifying a base URL is required when passing an API token so the description cannot redirect the credential to another destination.

The server retains the accepted description when the API specification changes, allowing updates to be reviewed before they take effect. Large APIs can use discovery mode, which exposes a smaller fixed set of tools, while execute_code can combine multiple API calls and return only the resulting data.

Setup and configuration

Node.js 22.19 or later, or Node.js 24.11 or later, is required; Node.js 23 is unsupported. macOS, Linux, and Windows are supported. The package can be run with npx, so a separate installation is not required.

Preview the generated tools with:

npx -y @kaisers-io/openapi-mcp@latest tools --spec https://api.example.com/openapi.json

Start it from an MCP host using the serve command and the same --spec option. If the description lacks an absolute server URL, add --base-url. Use check instead of serve to validate the configuration without starting the server.

For credentials, map a request header to an environment variable with --header-env, or use the supported file-based header option. The host must pass the environment variable through to the MCP process. Additional configuration covers specification headers, upstream OAuth client credentials, HTTP transport tokens, filters, timeouts, retries, and multiple APIs.

Tools and capabilities

• Converts OpenAPI 3.0, 3.1, and 3.2 operations into MCP tools.
• Reads specifications from URLs or local files.
• Provides tools, check, and serve command-line workflows.
• Defaults to GET, HEAD, and QUERY operations.
• Filters exposure with allow and deny selectors.
• Validates request arguments and applicable responses against schemas.
• Redacts configured credentials from model-visible output, errors, and logs.
• Supports discovery and execute_code modes for APIs with many operations.
• Supports local stdio use and serving over HTTP.
• Supports API keys, bearer tokens, and OAuth client credentials.

Limitations and notes

Swagger 2.0 descriptions are not supported. The OpenAPI description is partly treated as model-facing content: operation names, summaries, and parameter text are placed before the agent, so only descriptions from trusted sources should be used.

The server does not deploy an API or generate adapter code. Its behavior depends on the selected specification, filters, base URL, credential configuration, and MCP host settings. Other platforms may be refused because they are untested.