Openapi MCP Gateway

What mroops0111/openapi-mcp-gateway does

mroops0111/openapi-mcp-gateway turns OpenAPI or Swagger descriptions into MCP servers and can expose an existing FastAPI application through the same gateway. A single process can mount multiple APIs, with each one receiving a separate endpoint at /{name}/mcp. The gateway can also apply per-API authentication, request and response transformations, and exposure settings from YAML rather than requiring changes to the source specifications.

Generated operations are normally presented as MCP tools. Read-only GET operations that meet the gateway's eligibility rules can instead be promoted to MCP resources, giving clients URI-addressable data and resource templates. For very large APIs, dynamic exposure groups operations behind three meta-tools: list available operations, retrieve an operation's details, and call the selected operation. This avoids placing thousands of individual tool schemas into the client's context.

How it works

At startup, the gateway reads one or more specifications and builds an MCP endpoint for each configured API. Calls are authorized, converted into upstream HTTP requests or in-process ASGI calls for FastAPI routes, and then returned to the MCP client. JSONata expressions can reshape outgoing requests and incoming responses; expressions are validated when the gateway starts.

Authentication separates access to the MCP endpoint from the credential sent to the upstream API. Supported configurations include open access, fixed bearer tokens, API-key headers, caller-token passthrough, OAuth2 client credentials, authorization code, and token exchange. Authorization-code and token-exchange flows obtain per-user upstream credentials, while client-credentials uses one service token for callers. The gateway can store OAuth tokens in memory or, with the optional Redis extra, in Redis for multi-replica deployments.

FastAPI routes can be exposed in-process with the @mcp_tool decorator, avoiding a second network hop and a separate OpenAPI specification for those routes.

Setup and configuration

Install the Python package with uv add openapi-mcp-gateway; Python 3.11 or newer is required. uvx openapi-mcp-gateway runs the published package without a local installation. A container image is also published to GHCR and can read a mounted config.yml from /config.

For a single public API, provide a specification URL and a name:

uv run openapi-mcp-gateway \
  --spec https://petstore3.swagger.io/api/v3/openapi.json \
  --name petstore

The resulting MCP endpoint is available at http://127.0.0.1:8000/petstore/mcp by default. Multiple APIs are configured under servers in YAML, with options such as spec, name, base_url, exposure, and auth. Environment-variable references can supply secrets such as bearer tokens, API keys, and OAuth client credentials. Use --transport stdio for local desktop or IDE clients that launch the gateway as a subprocess.

Tools and capabilities

• Generate MCP tools from OpenAPI operations.
• Mount several APIs under distinct MCP paths in one process.
• Replace individual operation exposure with dynamic list, get, and call meta-tools.
• Promote eligible GET operations to MCP resources and resource templates.
• Rename operation IDs and hide parameters through YAML configuration.
• Transform requests and responses with JSONata.
• Forward fixed credentials, API keys, caller tokens, service tokens, or per-user OAuth2 tokens.
• Decorate FastAPI routes with @mcp_tool for in-process exposure.

Limitations and notes

Each mounted API has its own endpoint and authentication configuration, so clients must connect to the relevant path. Fixed bearer and API-key credentials are shared by callers; per-user credentials require the OAuth2 authorization-code or token-exchange flows. Redis is an optional dependency for sharing OAuth token state across replicas. The gateway's OAuth callback configuration uses the public base URL configured for the deployment.