OpenAPI to MCP Server

OpenAPI to MCP

Standalone proxy that turns any OpenAPI/Swagger-described HTTP API into an MCP (Model Context Protocol) server. It loads the spec at startup, filters operations by include/exclude, and registers one MCP tool per API operation. Tool calls are executed as HTTP requests to the backend API.

Useful when you already have (or want) a REST API with an OpenAPI/Swagger spec: the same spec drives both human-readable API docs and MCP tools for AI clients.

How it works

flowchart LR
  subgraph startup["Startup"]
    A[OpenAPI specURL or file] --> B[Load and filterinclude or exclude]
    B --> C[N MCP toolsone per operation]
  end

  subgraph runtime["Runtime"]
    D[MCP client] <-->|Streamable HTTPPOST/GET /mcp| E[openapi-to-mcp]
    E <-->|HTTP| F[Backend API]
  end

  C -.->|registered in| E

Logging and Correlation IDs

The server includes comprehensive logging with correlation ID support for request tracking:

• Correlation ID: Extracted from X-Correlation-ID header (case-insensitive) or auto-generated for each request
• Log levels: DEBUG, INFO, WARN, ERROR (configurable via MCP_LOG_LEVEL env var, default: INFO)
• Log format: [correlation_id] LEVEL message with optional context data
• Request tracking: All logs include correlation ID for tracing requests through the system

For E2E testing, pass X-Correlation-ID header with your request to track it across all logs.

1. Load OpenAPI spec from MCP_OPENAPI_SPEC (URL starting with http:// or https://, or file path).
2. Collect operations (method + path). Filter: if MCP_INCLUDE_ENDPOINTS is set, keep only those; otherwise drop any in MCP_EXCLUDE_ENDPOINTS. Include has priority over exclude.
3. For each operation create an MCP tool: name = MCP_TOOL_PREFIX + path segment (e.g. api_ + messages = api_messages). Path parameters are included in the tool name (e.g. /channels/{username} becomes channels_username). If the same path segment is used by more than one method (e.g. GET and PUT on /pet/{id}), the tool name is made unique by appending the method (e.g. pet_id_get, pet_id_put). Input schema from parameters and requestBody (Zod), handler = HTTP call to MCP_API_BASE_URL.
4. Load MCP server instructions: by default uses info.description from OpenAPI spec. Optionally, load custom instructions from MCP_INSTRUCTIONS_FILE and combine with OpenAPI description according to MCP_INSTRUCTIONS_MODE (default/replace/append/prepend). If file loading fails, server logs a warning and continues with OpenAPI instructions only.

Transport: Streamable HTTP. Endpoint: POST /mcp and GET /mcp.

Environment variables (MCP_ prefix)

Environment variables are loaded from .env file in the project root (using dotenv). You can also set them directly in your shell environment. See .env.example for a template.

MCP_OPENAPI_SPEC must be set. If it starts with http:// or https://, it's treated as a URL; otherwise, it's treated as a file path.

**Backw