mcp-gateway 发布 v7.0：为 MCP 服务器提供统一网关

Live demo: try the dashboard with simulated traffic — https://harrisoncn.github.io/mcp-gateway/ (runs entirely in your browser).

The Problem

As MCP becomes the standard protocol for AI agents to interact with tools, teams are running dozens of MCP servers — filesystem, GitHub, databases, Slack, search, and more. Managing them is chaos:

• Every AI client connects to every server independently
• No central authentication or access control
• No visibility into which tools are being called, by whom, and how often
• No rate limiting to prevent runaway agents from hammering your APIs

mcp-gateway solves this. It sits between your AI clients and your MCP servers, acting as a single, observable, secure entry point.

┌─────────────────────────────────────────────────────────┐
│                      AI Clients                         │
│   Claude Code · Cursor · Copilot · Your App · Scripts   │
└─────────────────────┬───────────────────────────────────┘
                      │  HTTP / REST
                      ▼
┌─────────────────────────────────────────────────────────┐
│                   mcp-gateway                           │
│                                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐  │
│  │   Auth   │  │  Router  │  │  Metrics / Monitor   │  │
│  │ API Key  │  │ Tool →   │  │  Prometheus · Logs   │  │
│  │   JWT    │  │ Server   │  │  Dashboard           │  │
│  └──────────┘  └──────────┘  └──────────────────────┘  │
│                                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │Rate Limit│  │ Registry │  │  Health  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└──────┬──────────────┬──────────────┬────────────────────┘
       │              │              │  stdio / SSE / WS
       ▼              ▼              ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│Filesystem│  │  GitHub  │  │PostgreSQL│  ... more
│  Server  │  │  Server  │  │  Server  │
└──────────┘  └──────────┘  └──────────┘

Features

• Unified API endpoint — one URL for all your MCP tools, auto-routed by tool name
• MCP endpoint for clients — /mcp speaks MCP Streamable HTTP (2025-06-18 / 2025-03-26), so Claude Code, Cursor or any MCP client sees every upstream tool through one server, with the same auth, limits and metrics — including progress notifications, cancellation, logging, completions and resource subscriptions
• Every MCP transport — stdio, streamable-http (current spec), legacy sse (HTTP+SSE) and websocket upstream servers, with per-server headers for upstream auth
• Automatic reconnect — crashed or disconnected servers are reconnected with exponential backoff + jitter; state is visible in /servers, /health, the dashboard and Prometheus
• Authentication — API keys (constant-time compare, storable as sha256: digests, with expiry), JWT (HMAC secret, PEM public key or JWKS URL; issuer / audience / exp checks), or no-auth; misconfiguration fails closed
• Hardening — security headers + hash-based CSP, IP allowlist, Host / Origin checks against DNS rebinding, body and argument size limits, brute-force lockout, secret redaction in logs and history, startup security warnings (mcp-gateway validate --strict)
• Rate limiting — per-key sliding-window counter, with standard X-RateLimit-* headers
• Per-key scopes — restrict an API key (or a JWT via claims) to some servers / tools and give it its own rate limit; enforced on REST and /mcp
• Concurrency limits — per-server maxConcurrency, queued requests count against timeout
• Health monitoring — periodic MCP ping health checks with latency (every 30 s, configurable)
• Metrics — Prometheus-compatible /metrics endpoint (monotonic counters) + JSON aggregation
• Config hot reload — servers, API keys / auth, rate limits, CORS and reconnect policy apply without a restart (disable with --no-watch)
• Optional auth for health & metrics — keep /health and /metrics public (default) or put them behind auth; the dashboard asks for a key
• Tool discovery — GET /api/v1/tools lists all tools across all servers
• Resources & prompts — resources/* and prompts/* from every server, aggregated on REST and /mcp
• Persistent audit log — optional SQLite history (built-in node:sqlite, no dependency) queryable via GET /api/v1/requests and the dashboard
• Tool filtering — per-server tools.allow / tools.deny glob patterns hide tools you don't want exposed (and block calls to them)
• YAML/JSON config — simple, declarative configuration with env var overrides
• Docker-ready — official Docker image, Compose examples included
• TypeScript SDK — embed the gateway as a library in your own project
• Client libraries — a dependency-free TypeScript client (clients/js, browser + Node) a Kotlin/JVM/Android client (clients/kotlin), and Python, Go and Swift SDKs (clients/python, clients/go, clients/swift)
• LLM tool schemas — GET /api/v1/tools?format=openai|anthropic returns ready-to-use function-calling definitions

Quick Start

Install

npm install -g @winstonsayno/mcp-gateway
# or
npx @winstonsayno/mcp-gateway init

Configure

# Generate a default config file
mcp-gateway init

# Edit mcp-gateway.yml to add your servers

# mcp-gateway.yml
port: 4000

servers:
  - id: filesystem
    name: Filesystem
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

  - id: github
    name: GitHub
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

Run

mcp-gateway start
# → mcp-gateway listening on http://0.0.0.0:4000
# → ✓ Filesystem — 8 tools available
# → ✓ GitHub — 26 tools available

Call a Tool

# List all available tools
curl http://localhost:4000/api/v1/tools

# Call a tool (auto-routes to the right server)
curl -X POST http://localhost:4000/api/v1/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "read_file", "arguments": {"path": "/tmp/hello.txt"}}'

# With authentication
curl -X POST http://localhost:4000/api/v1/tools/call \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"tool": "create_issue", "server": "github", "arguments": {"title": "Bug report", "body": "..."}}'

Use the gateway as an MCP server (/mcp)

The gateway is itself an MCP server: http://<host>:4000/mcp implements the Streamable HTTP transport (protocol 2025-06-18, 2025-03-26 accepted). Clients get one aggregated, filtered tool list; calls are routed to the right upstream server with the gateway's auth, rate limit, maxConcurrency, timeouts, metrics and request log.

Claude Code

claude mcp add --transport http gateway http://localhost:4000/mcp \
  --header "Authorization: Bearer your-secret-key"

Cursor (~/.cursor/mcp.json or .cursor/mcp.json)

{
  "mcpServers": {
    "gateway": {
      "url": "http://localhost:4000/mcp",
      "headers": { "Authorization": "Bearer your-secret-key" }
    }
  }
}

Clients that only speak stdio (e.g. older Claude Desktop builds) can bridge with mcp-remote: npx mcp-remote http://localhost:4000/mcp --header "Authorization: Bearer your-secret-key".

Any SDK client

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(new URL('http://localhost:4000/mcp'), {
  requestInit: { headers: { Authorization: 'Bearer your-secret-key' } },
}));
const { tools } = await client.listTools();

What the endpoint does:

API Reference

/health and /metrics are unauthenticated by default; set auth.protect.health / auth.protect.metrics to require auth for them too (/health/live and /health/ready always stay public for Docker / Kubernetes probes). Every other route requires auth when it is enabled. /metrics returns JSON by default (?window=<ms>); with monitor.prometheus: true it returns the Prometheus text format when the client asks for text/plain (as Prometheus does) or passes ?format=prometheus.

LLM tool schemas

GET /api/v1/tools?format=openai (Chat Completions), openai-responses (Responses API) or anthropic (Messages API) returns the tools the caller may use as function-calling definitions, plus a mapping from each LLM tool name back to the gateway server and tool:

{
  "format": "anthropic",
  "tools": [{ "name": "github__create_issue", "description": "…", "input_schema": { "type": "object", "properties": { … } } }],
  "mapping": { "github__create_issue": { "server": "github", "tool": "create_issue" } },
  "total": 1
}

Pass tools straight to the provider; when the model calls a tool, look it up in mapping and POST /api/v1/tools/call with that server / tool (the clients' callLlmTool() does this). Names follow mcp.toolNaming, are sanitised to ^[a-zA-Z0-9_-]{1,64}$ and de-duplicated; $schema is stripped and parameters is always an object schema. Scopes and ?server= / ?tag= filters apply.

Client libraries

Both are in this repository and not yet published to npm / Maven Central.

POST /api/v1/tools/call responses:

Configuration Reference

port: 4000                    # HTTP port (env: MCP_GATEWAY_PORT)
host: 0.0.0.0                 # Bind address (env: MCP_GATEWAY_HOST)
logLevel: info                # debug | info | warn | error

auth:
  strategy: api-key           # none | api-key | jwt | oauth2 (OAuth 2.1 resource server, see docs/configuration.md)
  apiKeys:
    - "your-secret-key"       # full access
    - "sha256:…"              # a key stored as its digest (mcp-gateway gen-key / hash-key)
    - key: "${APP_KEY}"       # scoped key (see "Per-key scopes")
      name: app
      expiresAt: "2027-01-01" # optional expiry; disabled: true switches a key off
      scope:
        servers: ["github"]
        tools: ["read_*"]
        rateLimit: { limit: 30, windowSeconds: 60 }
  protect:
    health: false             # true → /api/v1/health requires auth
    metrics: false            # true → /api/v1/metrics requires auth (configure your scraper)

reconnect:                    # automatic reconnect of crashed / disconnected servers
  enabled: true
  initialDelayMs: 1000        # first retry delay
  maxDelayMs: 60000           # backoff cap
  multiplier: 2               # delay *= multiplier after each failure
  jitter: 0.2                 # ±20 % randomisation
  maxAttempts: 0              # 0 = retry forever; else give up (status: offline)

health:
  intervalMs: 30000           # MCP ping interval
controlPlane:
  dashboard: true             # serve /dashboard

rateLimit:
  limit: 100                  # Max requests per window
  windowSeconds: 60           # Window duration
  perKey: true                # Per-key or global

monitor:
  requestLog: true            # Log all requests
  prometheus: true            # Enable Prometheus /metrics
  retentionHours: 24          # Metrics retention

security:                     # hardening (see docs/configuration.md#security)
  authLockout: true           # 429 for IPs with repeated auth failures
  dnsRebindingProtection: false  # true for a local gateway without auth
  ipAllowlist: ["10.0.0.0/8"]
  maxToolArgumentsBytes: 262144

cors:
  origins:
    - "https://your-app.com"

audit:                        # persistent request history (SQLite, Node 22.5+; default off)
  enabled: false
  path: mcp-gateway-audit.db
  retentionDays: 30           # 0 = keep forever

mcp:                          # downstream MCP endpoint (Streamable HTTP)
  enabled: true               # restart required to change
  path: /mcp                  # restart required to change; not "/" or under /api, /dashboard
  toolNaming: auto            # auto | prefix  ("<serverId>__<tool>")
  pageSize: 500               # tools per tools/list page
  sessionIdleTimeoutSeconds: 1800
  maxSessions: 1000           # least recently used idle session is evicted beyond this
  # allowedOrigins: ["https://your-app.com"]   # browser origins allowed on /mcp (default: cors.origins)
  # instructions: "Tools for the ACME workspace"  # returned from initialize

servers:
  - id: my-server             # Unique identifier
    name: My Server           # Display name
    transport: stdio          # stdio | streamable-http | sse | websocket
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    env:
      MY_VAR: "${ENV_VAR}"    # Environment variable substitution
    tags: [files, local]
    enabled: true
    timeoutMs: 30000          # ms, includes time queued behind maxConcurrency (schema v4: timeout)
    maxConcurrency: 10        # max in-flight tool calls for this server
    tools:                    # optional: expose only some tools (globs: * and ?, deny wins)
      allow: ["read_*", "list_*"]
      deny: ["*_secret"]
    reconnect:                # optional per-server override of the reconnect block
      maxAttempts: 5

  - id: remote
    name: Remote server
    transport: streamable-http   # MCP 2025-03-26+ (POST + optional SSE responses, Mcp-Session-Id)
    url: https://mcp.example.com/mcp
    headers:
      Authorization: "Bearer ${REMOTE_MCP_TOKEN}"   # ${VAR} expanded from the gateway's env

  - id: legacy
    name: Legacy SSE server
    transport: sse            # MCP 2024-11-05 HTTP+SSE (GET stream + POST to the announced endpoint)
    url: http://localhost:8080/sse

  - id: socket
    name: WebSocket server
    transport: websocket      # one JSON-RPC message per frame, "mcp" subprotocol
    url: ws://localhost:8081
    subprotocol: mcp          # "" to request no subprotocol

Hot reload

With mcp-gateway start the config file is watched (disable with --no-watch). On save:

An invalid file is rejected and the running config is kept. MCP_GATEWAY_* env overrides keep precedence.

Per-key scopes

Give each app its own key and only the tools it needs. Plain string keys keep full access; object entries can be restricted (all fields except key are optional):

auth:
  strategy: api-key
  apiKeys:
    - "admin-key"                       # unrestricted
    - key: ${AURA_GATEWAY_KEY}          # ${VAR} is expanded in object keys
      name: aura                        # client id "key:aura" in logs, metrics and sessions (unique)
      scope:
        servers: ["github", "fs-*"]       # server id globs
        tools: ["read_*", "github/create_issue"]   # tool globs; "server/tool" when the pattern has a "/"
        rateLimit: { limit: 30, windowSeconds: 60 } # own bucket instead of the global rateLimit

• A tool must pass the server's own tools filter and the key's servers and tools lists. An absent list means no restriction; an empty list allows nothing.
• Discovery hides what a key may not use: GET /tools, GET /servers, GET /servers/:id (→ 404), /mcp tools/list.
• Calls are refused: POST /tools/call and POST /servers/:id/reconnect → 403; /mcp tools/call → JSON-RPC error -32003. Auto-routing only considers servers the key may use, so a name that collides elsewhere can still be called without "server".
• On /mcp, collision prefixes are computed from what the key can see (a key scoped to one server sees bare names).
• Restricted keys only see their own entries in GET /requests.
• JWT: put globs in the mcp_servers / mcp_tools claims (array, or a space/comma-separated string), e.g. {"sub": "user-1", "mcp_servers": ["github"], "mcp_tools": "read_* github/create_issue"}. A malformed claim allows nothing.
• Hot reloadable: changing scopes applies to the next request; open /mcp sessions get notifications/tools/list_changed, and sessions of removed keys are closed.

Resources & prompts

Servers that announce the resources / prompts capabilities have their resources, resource templates and prompts listed at connect time (and refreshed on notifications/*/list_changed). They are available on REST (/api/v1/resources, /resources/templates, /resources/read, /prompts, /prompts/get) and on /mcp. Reads and gets are forwarded live with the server's timeout, counted against the rate limit and recorded in metrics / history with kind: "resource" or "prompt". Key scopes apply by server (servers globs); tools globs and servers[].tools filters only concern tools.

curl -s localhost:4000/api/v1/resources
curl -s -X POST localhost:4000/api/v1/resources/read -H 'content-type: application/json' -d '{"uri":"file:///notes/todo.md"}'
curl -s -X POST localhost:4000/api/v1/prompts/get -H 'content-type: application/json' \
  -d '{"name":"review-code","server":"github","arguments":{"pr":"42"}}'

Persistent audit log

By default request history lives in memory (monitor.retentionHours). Enable the audit log to keep it in SQLite across restarts:

audit:
  enabled: true
  path: ./data/mcp-gateway-audit.db   # default mcp-gateway-audit.db (WAL mode)
  retentionDays: 30                   # pruned hourly; 0 = keep forever

• Uses Node's built-in node:sqlite (Node 22.5+): no extra dependency and nothing native to compile. Node 22.0–22.4 refuses to start with audit.enabled: true and says why. Node may print an ExperimentalWarning for node:sqlite.
• Only metadata is stored: time, server, tool / URI / prompt, kind, duration, success, error message, client id, via (rest / mcp). Arguments and results are never stored.
• GET /api/v1/requests then reads from the database ("source": "audit") and supports filters (server, tool, client, success=true|false, via=rest|mcp, kind=tool|resource|prompt, since / until as ISO or epoch ms) and paging (nextCursor → ?cursor=). Restricted keys only ever see their own records. The dashboard's Request History panel has the same filters and a Load older button.
• Library users can plug in any store: metrics.setAuditStore(myStore) with the AuditStore interface.
• Changing audit requires a restart.

Tool filtering

Expose only part of a server's tools — e.g. make a filesystem server read-only, or drop tools that clash with another server's names:

servers:
  - id: filesystem
    name: Filesystem (read-only)
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
    tools:
      allow: ["read_*", "list_*", "search_files", "get_file_info"]
      deny: ["*_media_file"]

• Patterns are globs matched against the whole tool name, case-sensitive: * = any characters, ? = one character.
• A tool is exposed when it matches an allow pattern (or allow is absent / empty) and no deny pattern. Deny wins.
• Hidden tools are absent from GET /tools, GET /servers/:id, tool counts and metrics, and don't cause name conflicts with other servers. Calling one returns 404 (auto-routing) or 403 (explicit "server").
• The filter is applied to every tool list, including updates via notifications/tools/list_changed. Changing it in the config file is applied by hot reload (the server is reconnected).

Reconnect & server status

Each server's health.status is one of online, degraded (connected, but the health ping failed), reconnecting (lost — a retry is scheduled or running), offline (gave up, or reconnect disabled) or unknown. GET /api/v1/servers/:id also returns health.reconnect (state, attempt, nextAttemptAt, lastError, reconnects) and session (transport, negotiated protocolVersion, serverInfo, connectedAt).

Prometheus series added: mcp_gateway_server_up, mcp_gateway_server_status{status=…}, mcp_gateway_server_reconnects_total, mcp_gateway_server_reconnect_attempt, mcp_gateway_server_ping_ms.

Docker

# Pull and run
docker run -p 4000:4000 \
  -v $(pwd)/mcp-gateway.yml:/app/mcp-gateway.yml \
  -e GITHUB_TOKEN=ghp_... \
  ghcr.io/harrisoncn/mcp-gateway:latest

# Or with Docker Compose (gateway + Prometheus; see examples/docker)
cd examples/docker
GATEWAY_API_KEY=change-me docker compose up

The image's HEALTHCHECK uses the always-public /api/v1/health/live, so it keeps working when auth.protect.health is on.

Liveness vs. readiness (Kubernetes, load balancers)

A server counts as ready when it is enabled, connected and not degraded (failing health pings). By default every enabled server must be ready; ?min=N requires at least N instead (useful when some servers are optional). With no servers configured the gateway is ready. While shutting down it answers 503 {"status":"shutting_down"} so load balancers drain it first. The body only carries counts:

{ "status": "not_ready", "servers": { "ready": 1, "total": 2, "required": 2 } }

# Kubernetes
livenessProbe:
  httpGet: { path: /api/v1/health/live, port: 4000 }
readinessProbe:
  httpGet: { path: /api/v1/health/ready, port: 4000 }   # or /api/v1/health/ready?min=1
  periodSeconds: 10

Dashboard

Open http://localhost:4000/dashboard. The first visit opens a short guided setup: connect with an API key, see the upstream servers, call a tool from a form generated from its JSON schema, and copy a ready-made config for Claude Desktop, Cursor, Claude Code, the JS / Kotlin clients or curl. Reopen it any time with the ? button. After that the dashboard shows live request rate, p50 / p95 latency, error rate, top tools, usage per key, a live request stream, server health (with reconnect) and the filterable request history. It is one static file with no build step and no CDN; English / 中文, dark / light, and it works on phones.

When auth is enabled the key is kept in the browser tab (sessionStorage, or localStorage with “remember”) and sent as Authorization: Bearer … on every API call. The page itself contains no data; set dashboard.enabled: false to stop serving it. See dashboard/README.md.

Embed as a Library

import { Gateway, loadConfig } from '@winstonsayno/mcp-gateway';

const config = await loadConfig('./mcp-gateway.yml');
const gateway = new Gateway(config);

await gateway.start();
// Gateway is now running at http://localhost:4000

// Graceful shutdown
process.on('SIGTERM', () => gateway.stop());

What's New in v7.0

⚠ Breaking release — read Migrating to 7.0. On 6.9: npx @winstonsayno/mcp-gateway@6.9 migrate --write.

What's New in v6.9

What's New in v6.8

What's New in v6.7

What's New in v6.6

What's New in v6.5

What's New in v6.4

What's New in v6.3

What's New in v6.2

What's New in v6.1

What's New in v6.0

What's New in v5.9

Getting ready for 6.0: npx @winstonsayno/mcp-gateway@5.9 migrate --write — see Migrating to 6.0.

What's New in v5.8

What's New in v5.7

What's New in v5.6

What's New in v5.5

What's New in v5.4

What's New in v5.3

What's New in v5.2

What's New in v5.1

What's New in v5.0

⚠ Breaking release — read Migrating to 5.0. On 4.9: npx @winstonsayno/mcp-gateway@4.9 migrate --write.

What's New in v4.9

What's New in v4.8

What's New in v4.7

What's New in v4.6

What's New in v4.5

What's New in v4.4

What's New in v4.3

What's New in v4.2

What's New in v4.1

What's New in v4.0

⚠ Breaking release — read Migrating to 4.0.

What's New in v3.9

Details: CHANGELOG · Migrating to 4.0.

What's New in v3.8

Details: CHANGELOG · Configuration.

What's New in v3.7

Details: CHANGELOG · Configuration.

What's New in v3.6

Details: CHANGELOG · Configuration.

What's New in v3.5

Details: CHANGELOG · Configuration.

What's New in v3.4

Details: CHANGELOG · Configuration.

What's New in v3.3

Details: CHANGELOG · Plugins guide.

What's New in v3.2

Details: CHANGELOG.

What's New in v3.1

Config: mcp.passthrough. Details: CHANGELOG.

What's New in v3.0

Breaking: config schema v3 (cors.origins, health.intervalMs), plugin API v2 — see the migration guide and the roadmap.

Details: CHANGELOG.

What's New in v2.9

Details: CHANGELOG.

What's New in v2.8

Details: CHANGELOG.

What's New in v2.7

Details: CHANGELOG.

What's New in v2.6

Details: CHANGELOG.

What's New in v2.5

Details: CHANGELOG.

What's New in v2.4

Details: CHANGELOG.

What's New in v2.3

Details: CHANGELOG.

What's New in v2.2

Details: CHANGELOG.

What's New in v2.1

Details: CHANGELOG.

What's New in v2.0

Details: CHANGELOG.

What's New in v1.7

Details: CHANGELOG.

What's New in v1.6

Details: CHANGELOG.

What's New in v1.5

Details: CHANGELOG.

What's New in v1.4

Details: CHANGELOG.

What's New in v1.3

Details: CHANGELOG.

What's New in v1.2

Details and upgrade notes: CHANGELOG.

What's New in v1.0

What's New in v0.2.0

API stability

mcp-gateway follows Semantic Versioning since 1.0.0. Within a major version (3.x now) the REST API under /api/v1, the /mcp endpoint behaviour, configuration keys, CLI commands / flags, root library exports and Prometheus metric names only change in backward-compatible ways (new fields, endpoints and options may be added — ignore unknown fields). Deep imports, log format, the dashboard and the audit database schema are not covered. Details: docs/api-reference.md#stability-and-versioning.

Roadmap

3.0 completes the 1.x / 2.x plan (transports, /mcp endpoint, security, OAuth, tenants, policy, caching, plugins, edge runtimes, bridges, policy as code, declarative config). What comes next — sampling / elicitation passthrough, request replay, WASM plugins, smart routing, secrets management, federation, compliance, a developer portal and 4.0 — is in docs/ROADMAP.md.

Contributing

Contributions are welcome! See CONTRIBUTING.md.

git clone https://github.com/HarrisonCN/mcp-gateway.git
cd mcp-gateway
npm install
npm run typecheck && npm test
npm run dev -- start -c examples/basic/mcp-gateway.yml

License

MIT © 2026 HarrisonCN

_{Built for the agentic era · If this helps you, please ⭐ star the repo}