MCP OpenAPI Bridge

Turn any OpenAPI 3.x spec into callable MCP tools at runtime.

Point the bridge at a spec — JSON or YAML — and every operation becomes an MCP tool with a real input schema: path, query, and header parameters plus the JSON request body. Calling a tool performs the HTTP request and returns a bounded, readable response. No code generation, no build step, no wrappers to maintain.

Tenth tool in the TokenSaver family: TokenSaver MCP maps repositories, MCP Context Budget audits tool costs, MCP Web Snapshot reads the web, MCP Log Tail summarizes logs, MCP Secret Scan guards commits, MCP JSON Lens explores data, MCP Gateway aggregates servers, commitsmith writes commits, MCP Injection Guard screens input, and OpenAPI Bridge connects APIs.

Product requirements: PRD.md · PRD.id.md (Bahasa Indonesia)

Why

Almost every API ships an OpenAPI spec, and almost no agent can call it without someone writing and maintaining a wrapper. The bridge closes that gap at runtime: the spec is the integration. Add a server, remove a server, change a schema — the tools follow.

Related MCP server: OpenAPI MCP Server

Quick start

List what a spec exposes:

npx -y mcp-openapi-bridge inspect ./openapi.yaml

# Petstore (5 tool(s), base https://api.example.com/v1)
- listpets  GET /pets — List pets
- createpet  POST /pets — Create a pet
- getpetbyid  GET /pets/{petId} — Find pet by ID
- deletepet  DELETE /pets/{petId} — Delete a pet
- gettree  GET /tree

Call an operation without any MCP client:

npx -y mcp-openapi-bridge call ./openapi.yaml getpetbyid --args '{"petId":"42"}' \
  --base-url https://api.example.com/v1 --header "Authorization: Bearer $TOKEN"

Serve it to your agent:

npx -y mcp-openapi-bridge serve ./openapi.yaml --read-only

MCP server

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-bridge", "serve", "./openapi.yaml"],
      "env": { "PETSTORE_TOKEN": "..." }
    }
  }
}

Every operation becomes a tool named from operationId (or METHOD /path when missing) with a description built from the summary and route.

How it works

1. Load the spec from a JSON or YAML file.

2. Resolve local $refs (schemas, parameters, request bodies) with recursion protection.

3. Index operations, merging path-level and operation-level parameters.

4. Generate one MCP tool per operation with a JSON Schema built from parameters plus a body property for JSON request bodies.

5. Invoke by mapping arguments to the URL, query string, headers, and body — then return the response capped by size and token budgets.

Options

Exit codes: 0 success, 1 request or HTTP failure, 2 usage error. call exits 1 on HTTP errors so scripts can gate on it.

Limitations (v0.1.0)

• Local $refs only; external files are rejected with a clear message.

• Cookie parameters are ignored.

• OpenAPI 3.x only (2.0 / Swagger is not supported).

• Response bodies are returned as text or pretty JSON; binary responses are capped, not decoded.

• No OAuth flow — pass tokens through --header or your MCP server env config.

Security notes

• The bridge itself stores nothing. Credentials live in your client config or shell.

• --read-only plus tag filters keep mutating operations away from an agent session.

• Responses are bounded by --max-bytes and --budget, so a huge API payload cannot flood the context.

• Requests go only to the configured base URL; no telemetry, no callbacks.

Development

npm install
npm run typecheck
npm run build
npm test

The suite covers spec loading (JSON + YAML), $ref resolution, operation indexing, schema generation, request building, live HTTP invocation against a local test API, MCP round trips, and CLI flows.

License

MIT — see LICENSE.