criteo/openapi-to-mcp

Use your OpenAPI specification to expose your API's endpoints as strongly typed tools.
Basic example for https://petstore3.swagger.io/ 🎉
More complex example, using Github's API:
This example use the bearer token auth (with a Github Personal Access Token) and force the tool naming strategy to "verb and path", as Github's operation ids are not valid tool names.
Install
As a Nuget tool: openapi-to-mcp
Or download the executables from the releases
Usage
OpenAPI support
- Currently, OpenAPI 2.0 and 3.0 are supported.
- 3.1 is not (at least not until microsoft/OpenAPI.NET supports it)
- Specifications can be JSON/YAML and local (file) or remote (URL)
- Only local $refs are supported
OpenAPI custom extensions
A set of custom extensions is available to customize how your API should be exposed:
- info.x-mcp-instructions (string): Textual instructions exposed by the MCP server during the initialize handshake
- operation.x-mcp-tool-name (string): Custom tool name
- operation.x-mcp-tool-description (string): Custom tool description
- operation.x-mcp-tool-enabled (boolean): Enabled/disabled a specific operation (enabled by default)
MCP features
Only STDIO transport is currently supported.
Tools
Operations ("endpoints") from your OpenAPI specification are translated to MCP tools
- All path/query/JSON body parameters are exposed (using their JSON schema)
- Response is returned as-is
- By default, the tool name is computed using first the operation.x-mcp-tool-name extension, then the operation.operationId and then {httpMethod}_{escaped_path}
- The tool naming strategy can be defined via the --tool-naming-strategy option.
- ⚠️Tools are discarded if their name don't match ^[a-zA-Z0-9_-]{1,64}$
- Tools description are extracted as follows: operation.x-mcp-tool-description ?? operation.description ?? path.description
Tool call and host
When a tool is called, the MCP server will call the underlying endpoint. To determine which host to call a combination of parameters are used:
- the --host-override option
- your specification first server's URL if it's an absolute URL
- the host of the remote OpenAPI provided
- otherwise, an error is thrown
For example running openapi-to-mcp https://petstore3.swagger.io/api/v3/openapi.json:
- https://petstore3.swagger.io/api/v3/openapi.json defines a server, but its URL is relative (/api/v3)