OpenAPI-MCP
OpenAPI-MCP turns OpenAPI document operations into MCP tools with an operation allowlist and a request preview
- 69 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Tools call real operations of your API, including writing ones if you expose them
- API keys and OAuth credentials are set in the server environment and go to outgoing calls
Install
- Works in
Manual install
pip install 'openapi-mcp-proxy==2.0.0rc1'Python 3.10 or newer is required. Start with `openapi-mcp` and the `OPENAPI_URL`, `SERVER_NAME`, `MCP_ALLOWED_OPERATIONS` variables.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Tools call real operations of your API, including writing ones if you expose them
- API keys and OAuth credentials are set in the server environment and go to outgoing calls
This is third-party code. Review the repository files before installing.
What it does
OpenAPI-MCP reads an OpenAPI document, a local JSON or YAML file or an HTTP(S) address, and exposes its operations as MCP tools. Besides tools it serves schema resources and a usage prompt. The default transport is stdio, with Streamable HTTP at `/mcp` and legacy SSE on explicit setting. Each operation becomes a tool named `<server>_<operationId>`, inputs are checked against the schema before a request, and a JSON body goes in the `body` argument. By default no operations are exposed. The wanted ones go in `MCP_ALLOWED_OPERATIONS` as an array of pairs such as `GET /pets`, matching is literal, and a malformed list stops startup. `MCP_OPERATION_POLICY=all` exposes everything. Every tool accepts `dry_run: true` and returns the prepared request without executing it. Outgoing call authorization goes through `MCP_AUTH_HEADERS` or OAuth client credentials.
Who it is for. Developers who give an agent access to their own or a third-party REST API from an OpenAPI description and want to limit the set of operations.
Good fit when
- An OpenAPI spec exists and you want an MCP server from it with no code
- Only safe methods are opened to the agent, for example `GET /pets` and `GET /pets/{petId}`
- Before a POST call you want to see the prepared request through `dry_run`
- Outgoing calls carry a key in a header or OAuth client credentials
- The spec is a local YAML file that is not published online
Not a fit when
- You need per-user authorization: the server has no per-user permission layer yet
- The API is not described in OpenAPI: the server reads only such a document
- You need a stable version: the current one is the candidate `2.0.0rc1`
Example request
Bring up OpenAPI-MCP for petstore.json so the agent can use only GET /pets and GET /pets/{petId}MCP
- Transport
- stdio, http, sse
- Authentication
- key is optional
Environment variables
OPENAPI_URLrequired- A local JSON or YAML file or an HTTP(S) address of the OpenAPI spec
MCP_ALLOWED_OPERATIONS- A JSON array of pairs such as GET /pets that are exposed as tools
MCP_AUTH_HEADERSsecret- Auth headers for outgoing calls as JSON or key=value
Limitations
Version `2.0.0rc1` remains a release candidate, version 1.0.4 does not contain these fixes, and the upgrade guide should be read before updating. Python 3.10 or newer is required. The operation policy applies to the whole server instance and to no single user, and a GET-only list does not guarantee harmless routes. Credentials go to outgoing calls, so restricted API keys are advisable. The default HTTP endpoint moved from `/sse` to `/mcp` and clients must be updated.
How to disable. Remove the server entry from the client configuration and run `pip uninstall openapi-mcp-proxy` in the environment where it was installed.
FAQ
How do I run OpenAPI-MCP?
Run `pip install 'openapi-mcp-proxy==2.0.0rc1'`, set `OPENAPI_URL`, `SERVER_NAME` and `MCP_ALLOWED_OPERATIONS` and start `openapi-mcp`. The MCP client starts the process itself.
Which operations are available by default?
None. The wanted ones are listed in `MCP_ALLOWED_OPERATIONS`, and `MCP_OPERATION_POLICY=all` exposes all.
What does dry_run do?
With `dry_run: true` the tool returns the prepared URL, parameters and body and does not execute the request. Configured auth headers stay out of the preview.
How do I pass an API key?
Through `MCP_AUTH_HEADERS`, for example `{"X-API-Key": "..."}`, or through `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET` and `OAUTH_TOKEN_URL`. These credentials go to outgoing calls.
Which transport should I use?
stdio by default. For network use set `MCP_HTTP_ENABLED=true` and `MCP_HTTP_PORT`, and the endpoint will be `/mcp`.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server that loads a Swagger or OpenAPI spec and turns every API endpoint into a tool the agent can call.
A Pingora gateway that turns existing HTTP services into MCP servers from an OpenAPI spec, with no changes to their code
Apollo's MCP server: turns chosen GraphQL operations into tools the agent uses to work with your API
A single Go binary turns a SQL database into a REST API with roles and an MCP server for Claude Code, Cursor and VS Code
A Laravel and Lumen package that adds an MCP endpoint to your app's routes and attaches your own tools to it
mcp-graphql: MCP server for GraphQL APIs
mcp-graphql
Two GraphQL tools for MCP clients: the agent fetches your API schema and runs queries against a single endpoint
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| OpenAPI-MCP (this card) | no | key is optional | 69 | |
| OpenAPI MCP Server | yes | not required | 301 | another OpenAPI to MCP converter, while here all operations are closed by default, opened by list, with a dry_run preview |
| openapi-mcp-generator | no | 644 | generates a separate server project, while OpenAPI-MCP works as a proxy over the document itself |
README in short
The README describes installing the 2.0.0rc1 candidate, running it and configuring a client for stdio and Streamable HTTP. A section on choosing exposed operations follows, then request previews, an environment variable table, outgoing authentication and checks.