openapi-mcp-hub

Turn any OpenAPI spec — or a live PostgreSQL / MySQL database — into production-ready MCP endpoints. One process. One port. Zero code.

Install: pip install openapi-mcp-hub or uvx openapi-mcp-hub · Python 3.10+ · MIT

POST an openapi.json to the gateway and you instantly get an MCP endpoint any agent can call:

POST /services        →   http://your-gateway:20033/mcp/{service-name}

No wrapper code. No per-spec deployment. No port sprawl. Register as many services as you like — REST APIs or read-only databases — all behind a single port, hot-loaded the moment they register.

🇨🇳 中文文档看这里 · 📖 Full usage guide: USAGE.md (中文)

Why

• OpenAPI/Swagger is the de-facto standard for describing REST APIs — most internal services already have a spec.
• MCP (Model Context Protocol) is how agents consume tools — Claude Code and friends speak it natively over Streamable HTTP.
• Hand-writing MCP wrappers for every endpoint is repetitive and drifts out of sync. Running one MCP server per spec means port sprawl and linear ops cost.

openapi-mcp-hub is a gateway: one resident process, one port, path-level multi-tenancy (/mcp/{service}). Registration takes effect immediately — no restarts.

Public 2026 MCP ecosystem reports keep finding the same pain: only ~8.5% of MCP servers use OAuth, and tool-poisoning / rug-pull changes go unnoticed until an agent misbehaves. That is why this gateway treats data-plane auth and tool-change visibility as first-class features, not enterprise add-ons.

             ┌──────────── admin plane (admin token) ─────────────┐
             │  POST /services            register (REST or DB)   │
             │  GET  /services            list / inspect          │
             │  POST /services/preview    dry-run registration    │
             └────────────────────┬───────────────────────────────┘
                                  ▼
   Agents ── MCP (streamable HTTP / SSE) ──▶  openapi-mcp-hub gateway  ── HTTP ──▶  your APIs
   Claude Code, Cursor, custom clients        single port :20033   ── SQL ──▶  PostgreSQL / MySQL 8+
                                             per-service api_key

Install

pip install openapi-mcp-hub      # or: uvx openapi-mcp-hub
openapi-mcp-hub --version

Container (multi-arch: amd64 / arm64):

docker run -d --name openapi-mcp-hub -p 20033:20033 \
  -e OPENAPI_MCP_HUB_ADMIN_TOKEN=change-me \
  -v "$PWD/data:/app/data" \
  ghcr.io/zhangjk1207/openapi-mcp-hub:latest

CLI

Every flag is optional — with no arguments the gateway reads OPENAPI_MCP_HUB_* environment variables exactly as before. CLI wins over env.

--print-config exists because "why won't it start" is almost always a config question. It prints the effective config with credentials masked (never the value itself) and exits without starting the server. CLI help and log messages are in Chinese; flag names and env vars are stable.

Quickstart — 60 seconds

git clone https://github.com/zhangjk1207/openapi-mcp-hub && cd openapi-mcp-hub
docker compose up -d       # gateway + PostgreSQL + demo API, auto-registers a petstore service

Open http://localhost:20033 and paste the demo admin token: demo-admin-token — the console shows a ready-to-use petstore service (fixed demo key, listed below).

Try the agent-callable endpoint right away:

curl -X POST http://localhost:20033/mcp/petstore \
  -H "X-Api-Key: psk-demo-petstore-key" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_pets","arguments":{"limit":3}}}'

And in Claude Code:

claude mcp add --transport http petstore http://localhost:20033/mcp/petstore \
  --header "X-Api-Key: psk-demo-petstore-key"

The demo mode (OPENAPI_MCP_HUB_DEMO=1 in docker-compose.yml) uses a fixed, publicly-documented key for a friction-free tour. Turn it off (and change OPENAPI_MCP_HUB_ADMIN_TOKEN) before any real use — real registrations always mint a fresh one-time key.

Register your own API

ADMIN_TOKEN=demo-admin-token

# spec_text receives the raw file content (JSON or YAML)
jq -n --rawfile s your-openapi.json '{name:"my-api", base_url:"https://api.example.com", spec_text:$s}' | \
  curl -X POST http://localhost:20033/services \
    -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" -d @-

Connect it to Claude Code (the response includes a ready-to-run command):

claude mcp add --transport http my-api http://localhost:20033/mcp/my-api \
  --header 'X-Api-Key: psk-xxxx'

That's it — your API's operations are now agent-callable tools.

Connect your agent

Any MCP client that speaks Streamable HTTP works. The endpoint is http://<host>:20033/mcp/<service> and it authenticates with the per-service key in an X-Api-Key header (or a JWT Authorization: Bearer when the service runs in OAuth 2.1 resource-server mode).

The JSON shape below is the de-facto common one — clients that use mcpServers accept it verbatim:

{
  "mcpServers": {
    "petstore": {
      "url": "http://localhost:20033/mcp/petstore",
      "headers": { "X-Api-Key": "psk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Field names drift between client versions — where a client differs (VS Code uses servers, not mcpServers), that client's own docs are authoritative. The gateway side never changes: one URL, one header.

Legacy SSE clients (older than Streamable HTTP) use the compatibility endpoint with the same key:

GET http://localhost:20033/mcp/<service>/sse

stdio-only clients — use the built-in bridge

Some clients can only spawn a local process and talk JSON-RPC over stdin/stdout. The same package ships a bridge subcommand (uvx openapi-mcp-hub bridge …, or openapi-mcp-hub bridge … from a local install) that pipes stdio straight to a running gateway endpoint:

{
  "mcpServers": {
    "petstore": {
      "command": "uvx",
      "args": [
        "openapi-mcp-hub", "bridge",
        "--url", "http://localhost:20033/mcp/petstore",
        "--header", "X-Api-Key=psk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ]
    }
  }
}

The bridge is protocol plumbing only: it forwards every message unchanged, keeps Mcp-Session-Id sticky, derives the MCP-Protocol-Version / Mcp-Method / Mcp-Name headers from the client's own request, and turns transport-level failures (401, unreachable gateway) into JSON-RPC errors with an actionable data.hint. It does not cache, rewrite or re-implement anything, and it is not needed when the client can speak Streamable HTTP directly.

Verify from the shell without any client:

curl -s -X POST http://localhost:20033/mcp/petstore \
  -H "X-Api-Key: psk-…" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

Register a database instead of an API

No REST spec needed. Point the gateway at a database (via an environment variable name — the DSN itself never touches disk):

export WORKFLOW_DB_URL='postgresql://ro_user:pass@db.internal.example:5432/workflow'
curl -X POST http://localhost:20033/services \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"workflow-db","db":{"url_env":"WORKFLOW_DB_URL"}}'

You get three tools the agent can use blind: list_tables, describe_table (schema + comments embedded), and query (SELECT-only).

Read-only is enforced in six layers

Credentials are referenced by env var name only — nothing sensitive is persisted or logged. SQL digests land in the in-memory call log for auditing.

Features

Comparison

Security posture

Everything below ships in the free, self-hosted, single-binary build:

JWT mode in three commands (built-in issuance):

export OPENAPI_MCP_HUB_JWT_SECRET="$(openssl rand -hex 32)"
# register with authn={"mode":"jwt"} (see USAGE.md for external-IdP mode)
curl -X POST $GW/services -H "Authorization: Bearer $ADMIN" -d '{"name":"crm","spec_url":"...","base_url":"...","authn":{"mode":"jwt"}}'
curl -X POST $GW/services/crm/token -H "Authorization: Bearer $ADMIN" -d '{"ttl_s":3600}'
# → use the returned token as: Authorization: Bearer <token>

Console screenshots

Real console, not mockups — REST and database sources in one table, generated tool sets, health probes and key rotation, all from a single static page: no build chain, no external assets, works air-gapped.

Services — REST and database sources side by side, /mcp/{name} per row:

Service detail — endpoint, generated tools with descriptions, health probe, key rotation:

Register a REST API — spec upload / paste, path filters, target auth by env var name:

Register a database — DSN referenced by env var name only, read-only tool trio generated:

Roadmap

• v0.5.0 — agent-facing tool quality · tool annotations (readOnlyHint/destructiveHint) · description/schema compaction · actionable error hints · CLI flags · multi-arch ghcr image
• v0.4.0 — JWT data-plane auth (OAuth 2.1 resource server, RFC 9728) · tool-poisoning drift diff on update/refresh
• v0.3.0 — OAuth2 client_credentials target auth · spec refresh endpoint · call stats · console auth fix
• M5-1 — Database → MCP (PostgreSQL + MySQL 8, six-layer read-only)
• M5-2 — per-table tool mode, sensitive-column masking
• M5-3 — write operations (opt-in, statement allowlist)
• Metrics endpoint (Prometheus) & key expiry
• Per-tenant quotas / rate limiting
• Per-service circuit breaking

Deliberately not on this list: anything that turns the gateway into a platform (RBAC/SSO, multi-replica coordination, metric stacks, audit stores). Each of those makes the default path heavier for a problem the reverse proxy in front of you already solves.

Not implemented today — do not plan around these: circuit breaking, per-tenant rate limiting or quotas, HA / multi-replica coordination, Prometheus metrics, database write operations, per-table database tools, API-key expiry. Safety isolation today is per-service httpx client + independent timeout + connection-pool cap + the SSRF allowlist, all inside a single process.

Development

pip install -e ".[dev]"
pytest tests/ -q          # 279 pass; 22 opt-in integration tests skip without PG/MySQL DSNs

License

MIT