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

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.

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.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

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          # 178 pass; 22 opt-in integration tests skip without PG/MySQL DSNs

License

MIT