openapi-to-mcp

Purpose

openapi-to-mcp is an MCP server used to expose your API as strongly typed MCP tools through an OpenAPI specification, enabling AI Agents or MCP-compatible clients to directly call API endpoints.

Main capabilities

• Translate operations (endpoints) in the OpenAPI specification into MCP tools
• Expose all path parameters, query parameters, and JSON request body parameters (based on their JSON Schema)
• Responses are returned as-is
• Tool names are by default derived in order from the operation.x-mcp-tool-name extension, operation.operationId,{httpMethod}_{escaped_path} is calculated, and the naming strategy can also be defined via the --tool-naming-strategy option. Note: tools whose names do not match ^[a-zA-Z0-9_-]{1,64}$ will be discarded
• Tool descriptions are extracted in the order operation.x-mcp-tool-description, operation.description, path.description
• Supports Bearer Token authentication (--bearer-token option), which will be provided as the Authorization: Bearer {token} header for all calls, and is also used when fetching remote specifications
• Supports OAuth flows such as ClientCredentials, RefreshToken, and Password; if the corresponding securitySchemes are declared in the OpenAPI specification, their tokenUrl is used

OpenAPI support

• Currently supports OpenAPI 2.0 and 3.0, does not support 3.1 (unless supported by microsoft/OpenAPI.NET)
• The specification can be JSON or YAML, a local file or a remote URL
• Only local $refs are supported

Custom extensions

• info.x-mcp-instructions(string): text 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): enable/disable a specific operation (enabled by default)

Usage

• Installation: use as a NuGet tool openapi-to-mcp, or download the executable from releases
• Only STDIO transport is supported
• When a tool is called, the MCP server calls the underlying endpoint. The way the calling host is determined: the --host-override option, the URL of the first server in the specification (if it is an absolute URL), the host of the remote OpenAPI provider; otherwise an error is thrown
• For example, running openapi-to-mcp https://petstore3.swagger.io/api/v3/openapi.json: this specification defines a server, but its URL is a relative path (/api/v3), so the host of the specification's own URL https://petstore3.swagger.iois used, with the server's relative path appended

Applicable scenarios

• Developers who need to let AI Agents call existing APIs through the MCP protocol
• Scenarios where you want to quickly expose an API as strongly typed tools for AI use

Limitations

• OpenAPI 3.1 is not supported
• Only local $refs are supported
• Only STDIO transport is supported
• Tool names must conform to ^[a-zA-Z0-9_-]{1,64}$, otherwise they are discarded