Openapi MCP

What openapi-mcp does

The openapi-mcp MCP server turns an OpenAPI 3 specification into an MCP endpoint without generating source files or creating one implementation per API operation. Each operation in the document becomes a callable tool. The operation ID supplies the tool name, the summary supplies its description, and the declared parameters and request body define its input schema.

The server can read a specification from a local file or a URL. It uses the API address in servers[0].url unless you provide a replacement base URL. APIs that lack a specification can still be used after you write a small OpenAPI document describing the endpoints.

As a Developer Tools listing, it fits workflows where an AI client needs access to an existing HTTP API and the API owner already maintains an OpenAPI 3 description.

How it works

At startup, openapi-mcp loads the specification and resolves $ref references. It then creates the MCP tool definitions in memory. When a client calls a tool, the server makes the corresponding HTTP request and returns the status code and response body. Responses are limited to 50,000 characters.

The local mode communicates with an MCP client using JSON-RPC 2.0 over standard input and output. The HTTP mode accepts JSON-RPC requests at /mcp using POST. Start HTTP mode by placing --http <port> after the specification and optional base URL arguments.

Use TOOL_FILTER when a large API would expose more operations than the model can use effectively. Its regular expression determines which tool names are made available.

Setup and configuration

Node.js 18 or newer is required. Run the script with a local specification or a URL:

node openapi-mcp.mjs <spec-url-or-file> [base-url] [--http <port>]

For local clients, configure the client to launch node with the script and specification path. For remote use, start the HTTP listener and configure the client with the server URL. HTTP requests can be protected with MCP_AUTH_TOKEN, which requires a matching bearer token in the request’s Authorization header.

API_TOKEN supplies credentials for bearer, basic, API-key, and existing OAuth access-token schemes. The server places the value according to the specification’s security definitions. OAuth client-credentials flows use OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET; OAUTH_REFRESH_TOKEN can support refresh-token renewal. OAUTH_TOKEN_URL and OAUTH_SCOPE can override the token endpoint or requested scope. API_HEADERS adds JSON-encoded headers to every upstream request.

JSON specifications work directly. YAML requires installing the yaml package. A missing credential for a declared security scheme produces a startup warning on stderr.

Tools and capabilities

• Exposes one MCP tool for each OpenAPI operation.
• Supports local stdio and remote HTTP serving modes.
• Resolves specification references before building tools.
• Sends JSON request bodies.
• Supports bearer and basic authentication, API keys in headers, query parameters, or cookies, and selected OAuth2 flows.
• Filters exposed tools with a regular expression.

Limitations and notes

openapi-mcp supports OpenAPI 3, not Swagger 2.0. Convert Swagger specifications before use. Request bodies must be JSON; file uploads are not supported.

Authentication has defined boundaries. Interactive OAuth authorization-code login is not included. You must provide an access token or obtain credentials through another provider tool. One security scheme is selected for the API, while per-endpoint security overrides are not applied. Rotated refresh tokens remain only in memory and disappear when the process restarts.

HTTP mode uses plain HTTP, so place HTTPS in front of it when deploying remotely. It does not provide streaming, batch requests, or OAuth for clients connecting to the MCP server. Remote deployments also share the server’s upstream IP among users, which can affect API rate limits. Protect a remotely exposed instance with MCP_AUTH_TOKEN and account for the fact that the upstream API credentials are held by the server.