mcp-openapi-bridge

A generic MCP server that bridges any OpenAPI 3.x REST API to Claude Code — automatically generating one tool per endpoint from your spec.

Point it at an OpenAPI spec, set your auth token, and Claude can call every endpoint in your API with full argument validation.

Requirements

• Node.js >= 20

Related MCP server: MCP OpenAPI Connector

How it works

1. Loads your OpenAPI 3.x spec from a local file (OPENAPI_SPEC_PATH) or URL (OPENAPI_SPEC_URL)

2. Resolves $ref references and extracts all operations

3. Registers one MCP tool per operation (filtered by OPENAPI_MAX_TOOLS, tags, or path prefix)

4. Each tool accepts path params, query params, and a body for request bodies — plus per-call bearer_token and custom_headers overrides

5. Executes HTTP requests against API_BASE_URL and returns the response

Quick start

npm install -g mcp-openapi-bridge

Add to Claude Code:

claude mcp add mcp-openapi-bridge \
  -e API_BASE_URL=https://api.example.com \
  -e OPENAPI_SPEC_URL=https://api.example.com/openapi.json \
  -e OPENAPI_TOKEN=your-token

Or with a local spec file:

claude mcp add mcp-openapi-bridge \
  -e API_BASE_URL=https://petstore3.swagger.io/api/v3 \
  -e OPENAPI_SPEC_PATH=/path/to/openapi.yaml \
  -e OPENAPI_TOKEN=your-token

Environment variables

Required

Authentication

All auth mechanisms can be combined and are applied simultaneously:

Per-call overrides: Every tool also accepts bearer_token and custom_headers arguments. If provided, they override the global env vars for that single request. This lets Claude switch tokens per call without restarting the server.

Filtering (for large specs)

For APIs with hundreds of endpoints (Stripe, GitHub, Kubernetes), use these to scope down to the subset you need:

OPENAPI_INCLUDE_TAGS=payments,customers
# or
OPENAPI_PATH_PREFIX=/v1/charges

Transport

Requests to /mcp are capped at 10MB. See docs/architecture.md for how stdio and HTTP differ in what's isolated per client, and why API_BASE_URL is fixed per deployment rather than a per-request parameter.

Tool naming

• If the operation has an operationId, it's used directly (sanitized to [a-zA-Z0-9_]+)

• Otherwise: {method}_{path} — e.g. GET /orders/{id}/items → get_orders_id_items

• Duplicate IDs get a numeric suffix: getOrders, getOrders_2

Tool arguments

Each tool exposes:

• Path parameters — by name, required

• Query parameters — by name, optional

• body — request body for POST/PUT/PATCH (optional or required per spec)

• Header parameters — as header_{lowercase_name}

• bearer_token — per-call bearer override

• custom_headers — per-call extra headers ({"X-Tenant": "abc"})

Generic fallback tool

execute_rest is always registered for arbitrary requests when no specific tool fits:

execute_rest(method, path, query?, body?, headers?, bearer_token?, custom_headers?)

Docker

Stdio transport:

docker build -t mcp-openapi-bridge .
docker run -i --rm \
  -e API_BASE_URL=https://api.example.com \
  -e OPENAPI_SPEC_URL=https://api.example.com/openapi.json \
  -e OPENAPI_TOKEN=your-token \
  mcp-openapi-bridge

HTTP transport (for AWS Bedrock AgentCore or other hosted deployments):

docker build -f Dockerfile.agentcore -t mcp-openapi-bridge-agentcore .
docker run -p 8080:8080 \
  -e API_BASE_URL=https://api.example.com \
  -e OPENAPI_SPEC_URL=https://api.example.com/openapi.json \
  -e OPENAPI_TOKEN=your-token \
  -e MCP_AUTH_TOKEN=your-mcp-access-token \
  mcp-openapi-bridge-agentcore

For public-routable deployments, set MCP_AUTH_TOKEN and configure clients to send Authorization: Bearer <token> to /mcp.

Spec caching

When using OPENAPI_SPEC_URL, the spec is cached locally for 1 hour (in ~/.cache/mcp-openapi-bridge/). Override with OPENAPI_SPEC_CACHE_TTL_SECONDS.

Limitations (v1)

• OpenAPI 3.x only (not Swagger 2.0)

• Internal $ref only (no cross-file references)

• application/json bodies only (no multipart/form-data)

• No cookie parameters

• No OAuth2 token flows (static token only)

• No per-operation auth override

• allOf/anyOf/oneOf schemas fall back to z.any()

License

MIT