@winstonsayno/mcp-gateway weekly downloads statistics

mcp-gateway

English · 简体中文

17.0.0 is the current release — released by owner decision; external security review and dedicated-hardware soak not yet performed. 15.0.0 and 16.0.0 never shipped as stable releases, so 17.0.0 is the first stable major after 14.9 and carries every breaking change of 15.0, 16.0 and 17.0 (Node.js ≥ 24, config schema v13 only, plugin API v6 only, no inline module plugins). Test it in staging first; see release gates. Upgrading from 14.9: migrating to v15 · v16 · v17. Staying on 14.9: npm i @winstonsayno/mcp-gateway@v14-lts, image :14.

One authenticated, observable endpoint in front of all your MCP servers.

mcp-gateway sits between AI clients (Claude Code, Cursor, your own agents, LLM apps, web and mobile front-ends) and the Model Context Protocol servers they use. Clients connect once — over MCP Streamable HTTP at /mcp or a REST API under /api/v1 — and the gateway authenticates the caller, checks what it may do, routes the call to the right upstream and records what happened. Keys, scopes, rate limits, policy, logs and metrics live in one place instead of in every client.

Current release: 17.0.0 (npm latest). Live dashboard demo with simulated traffic, no backend: https://harrisoncn.github.io/mcp-gateway/

Contents

• Architecture
• Key features
• Quick start
• Minimal configuration
• Connect clients and LLMs
• Security model
• Observability
• Supported versions
• Documentation
• Contributing
• License

Architecture

flowchart LR
  subgraph Clients
    A["MCP clients<br/>Claude Code · Cursor · agents"]
    B["LLM apps<br/>OpenAI · Grok · DeepSeek · Claude"]
    C["Web / mobile apps<br/>JS · Kotlin · Swift · Python · Go"]
  end

  subgraph GW["mcp-gateway"]
    direction TB
    AU["Authentication<br/>API keys · JWT · OAuth 2.1"]
    PO["Authorization & policy<br/>scopes · tenants · tool policy · rate limits"]
    RT["Routing<br/>splits · load balancing · failover"]
    SM["Security modules<br/>DLP · sanitize · approvals · …"]
    CA["Cache<br/>tool cache · semantic cache"]
    FA["Final authorization<br/>against the routed target"]
    AD[("Audit log · metrics · traces")]
    AU --> PO --> RT --> CA --> SM --> FA
    FA -.-> AD
  end

  A -- "/mcp (Streamable HTTP)" --> AU
  B -- "/api/v1 (REST)" --> AU
  C -- "/api/v1 or /mcp" --> AU

  FA -- stdio --> U1["Local MCP servers"]
  FA -- "Streamable HTTP · SSE" --> U2["Remote MCP servers"]
  FA -- WebSocket --> U3["WebSocket MCP servers"]

Each call is authenticated, authorized against the caller's scope, routed (a routing split is decided and authorized before any cache lookup), passed through the configured security modules and then authorized once more against the final target right before it is sent upstream. Feature modules are loaded on demand: a module is only imported when its section is present in the config.

Key features

Core gateway

• MCP endpoint at /mcp (Streamable HTTP, protocol revisions 2025-11-25 back to 2024-11-05) that aggregates tools, resources and prompts from every upstream, with progress, cancellation, logging, completions and subscriptions.
• Upstream transports: stdio, streamable-http, legacy sse and websocket, with per-server headers and env.
• REST API under /api/v1: tool discovery and calls, resources, prompts, request history, live stats (SSE). GET /api/v1/tools?format=openai|openai-responses|anthropic returns function-calling schemas for LLM APIs.
• Reconnect with backoff and jitter, MCP ping health checks, per-server concurrency limits, timeouts and tool allow / deny filters.
• Hot reload of servers, keys, limits and CORS when the config file changes (start --no-watch to disable).

Access control

• API keys (constant-time compare, sha256: digests, expiry / disable), JWT (HMAC, PEM or JWKS; issuer / audience / exp checks) and OAuth 2.1 resource server per the MCP authorization spec. Misconfiguration fails closed.
• Per-key scopes (server and tool globs, own rate limit) for keys and JWT claims, enforced on REST and /mcp; tenants with roles; sliding-window rate limits; brute-force lockout.
• Network guards: IP allowlist, Host / Origin checks against DNS rebinding, body and argument size limits, security headers with a hash-based CSP. stdio servers run with an environment allowlist and optional uid / gid, cwd and sandbox wrapper (stdio isolation).…