MCP Gateway

One gateway between your AI and every tool it needs, without flooding the context window.

MCP Gateway is a single Rust binary that sits between an AI client and all of its tools. Connect MCP servers and REST APIs behind it, and the agent sees a compact meta-surface of 14 to 17 tools instead of every backend definition. It discovers and calls backend tools on demand. A small live-agent benchmark found no completed-task token saving from that extra hop, so the value is catalog capacity plus policy and routing—not a blanket token claim. See Benchmarks.

Personal and noncommercial use is free, including running the full gateway. Running it commercially needs a commercial license.

The problem this removes

Every MCP tool an AI client connects costs roughly 150 tokens of context overhead, loaded into every request whether the tool gets used or not. Connect 20 servers with 100 tools between them and you spend about 15,000 tokens before the conversation starts. Context limits then force a second cost: you have to decide up front which tools to connect and leave the rest out, so the agent makes worse decisions because it cannot reach data you chose not to load.

MCP Gateway moves the full catalog out of the exposed tool list. The agent loads a small fixed set of meta-tools, searches with gateway_search_tools, and invokes a backend tool with gateway_invoke. This creates room for larger catalogs, but the extra search hop can cost more tokens and time on a completed task.

flowchart LR
    AI["AI client<br/>(Claude, Cursor, ...)"]
    subgraph GW["MCP Gateway (single binary)"]
        META["Compact meta-surface<br/>14-17 tools"]
        DISC{"Discover on demand<br/>gateway_search_tools<br/>gateway_invoke"}
    end
    T1["MCP backend<br/>Tavily (stdio)"]
    T2["MCP backend<br/>Context7 (http)"]
    C1["REST capability<br/>GitHub"]
    C2["REST capability<br/>Stripe"]
    Cn["110+ capabilities"]

    AI -->|"14-17 tool defs"| META
    META --> DISC
    DISC --> T1
    DISC --> T2
    DISC --> C1
    DISC --> C2
    DISC --> Cn

Quick Start

Four commands:

brew trust --tap MikkoParkkola/tap   # Homebrew 6.0+
brew install MikkoParkkola/tap/mcp-gateway   # 1. install
mcp-gateway setup wizard --configure-client  # 2. import existing servers + wire up clients
mcp-gateway serve                            # 3. run
mcp-gateway doctor                           # 4. verify everything is healthy

That is it. Your AI clients now talk to the gateway, and the gateway routes to every backend you already had configured, at a flat ~15 tools instead of ~150. Start with gateway_search_tools from your AI client to find any backend tool, then invoke it with gateway_invoke.

Nothing to import yet? mcp-gateway init --with-examples writes a working gateway.yaml with public capabilities so you can confirm the gateway is alive before adding your own servers.

Or tell your AI assistant (recommended):

Read https://github.com/MikkoParkkola/mcp-gateway and install mcp-gateway to consolidate all my MCP servers behind one gateway

Your agent will install the binary, run the setup wizard, import your existing MCP servers, and wire itself up. This works in Claude Code, Cursor, Windsurf, Codex, and any AI with terminal access.

Install

Method	Command
Homebrew (macOS/Linux, recommended)	brew install MikkoParkkola/tap/mcp-gateway
Cargo	cargo install mcp-gateway
cargo-binstall	cargo binstall mcp-gateway
Direct binary download (Windows x64)	Download mcp-gateway-windows-x86_64.exe from the latest release
Docker	docker run -v $(pwd)/gateway.container.yaml:/config.yaml:ro ghcr.io/mikkoparkkola/mcp-gateway:latest --config /config.yaml

On Linux, the image runs as UID/GID 1001. Make an owner-only deployment copy instead of changing ownership on your working config: install -m 600 gateway.yaml gateway.container.yaml && sudo chown 1001:1001 gateway.container.yaml. Do not make a credential-bearing config world-readable. Docker Desktop handles bind-mount identity differently on macOS and Windows.

# macOS Apple Silicon
curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-darwin-arm64 -o mcp-gateway && chmod +x mcp-gateway

# macOS Intel
curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-darwin-x86_64 -o mcp-gateway && chmod +x mcp-gateway

# Linux x86_64
curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-linux-x86_64 -o mcp-gateway && chmod +x mcp-gateway

# Windows x64 (PowerShell)
Invoke-WebRequest -Uri https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-windows-x86_64.exe -OutFile mcp-gateway.exe

Set up, three ways

Option A: auto-import everything (recommended)

mcp-gateway setup wizard --configure-client

Scans Claude Desktop, Claude Code, Cursor, Zed, Continue.dev, Codex, and running MCP processes; lets you pick which servers to import into gateway.yaml; previews the gateway entry; writes it into each detected client config; verifies the write; and prints backup and rollback paths when an existing client config changes. Add --yes to skip the prompts and import everything.

Option B: add servers from the built-in registry

48 popular MCP servers are pre-registered with the right command, args, and env-var template. mcp-gateway add is compatible with claude mcp add and codex mcp add:

mcp-gateway add tavily                                       # known server, fills env vars
mcp-gateway add my-server -- npx -y @some/mcp-server --flag  # arbitrary stdio command
mcp-gateway add --url https://mcp.sentry.dev/mcp sentry      # HTTP server
mcp-gateway add -e API_KEY=xxx my-server -- npx my-mcp-server

mcp-gateway list shows what is configured. mcp-gateway remove <name> removes one.

Option C: hand-write gateway.yaml

For the full schema, see the annotated examples/gateway-full.yaml, which covers env_files, server, auth, meta_mcp, streaming, failsafe, cache, capabilities, and backends. The remaining top-level sections (playbooks, security, webhooks, routing_profiles, code_mode, mtls, key_server, agent_auth, runtime, marketplace, control_plane, cost_governance) have no prose reference yet; the Config struct in src/config/mod.rs is the authoritative list. Minimal example:

server:
  port: 39400

meta_mcp:
  enabled: true

backends:
  tavily:
    # `command` is parsed with host-platform rules: POSIX shlex on unix,
    # CommandLineToArgvW on Windows (so `C:\Windows\py.exe …` keeps its
    # backslashes; quote paths that contain spaces).
    command: "npx -y @anthropic/mcp-server-tavily"
    description: "Web search"
    env:
      TAVILY_API_KEY: "${TAVILY_API_KEY}"

  sentry:
    http_url: "https://mcp.sentry.dev/mcp"
    description: "Sentry issues"

Run and verify

mcp-gateway serve                  # start the gateway
mcp-gateway doctor                 # diagnose config, port, env vars, backend health
mcp-gateway doctor --fix           # auto-fix issues where possible

The web dashboard is at http://localhost:39400/ui once serve is running. The operator dashboard at /dashboard needs the admin credential, and a browser cannot send one on a navigation — so serve prints a single-use link to open it with, on a loopback bind. A network-bound gateway prints none and is managed through /ui with the token instead. See Opening the dashboard.

Connect AI clients (if you skipped Option A)

setup export writes the gateway entry into client config files for you. It auto-detects the right path per client:

mcp-gateway setup export --target all --dry-run       # preview without writing
mcp-gateway setup export --target all                 # write, back up, verify
mcp-gateway setup export --target claude-code         # one client
mcp-gateway setup export --target all --watch         # regenerate on gateway.yaml changes
mcp-gateway setup export --rollback <backup-file>     # restore one client config

Existing client files are backed up before mutation. The command prints the exact rollback command beside each updated client.

Client	Config path
claude-code	~/.claude.json
claude-desktop	platform-specific
cursor	.cursor/mcp.json (workspace)
vs-code-copilot	.vscode/mcp.json (workspace)
windsurf	~/.codeium/windsurf/mcp_config.json
cline	.cline/mcp_servers.json (workspace)
zed	~/.config/zed/settings.json

Modes: --mode proxy (HTTP), --mode stdio (subprocess), --mode auto (probe the health endpoint, then fall back).

{
  "mcpServers": {
    "gateway": {
      "type": "http",
      "url": "http://localhost:39400/mcp"
    }
  }
}

Why use MCP Gateway?

• Larger catalog, smaller exposed surface. The agent loads a fixed meta-surface instead of every backend definition. In the checked-in live run, both paths completed every task, but the meta path used 1.2–16.1% more input tokens and added one turn. See Benchmarks.
• Unlimited tools, discovered on demand. No more choosing which servers fit the budget. The agent searches (gateway_search_tools) and invokes (gateway_invoke) tools as it needs them.
• Add any REST API in minutes. Drop in a YAML file or import an OpenAPI spec with mcp-gateway cap import. 110+ capabilities ship built in.
• Per-user identity to backends. Multitenant backends can receive the verified end-user identity with no gateway-stored long-lived credential. See Multitenant identity.
• Secure by construction. A tool-poisoning validator scans every backend tool description before it reaches the agent. SHA-256 capability pinning is optional: unpinned files load, pinned files fail closed on mismatch. OWASP Agentic AI Top 10 coverage is self-assessed in-tree, not a certification. The crate sets #![deny(unsafe_code)], so any unsafe block needs an explicit #[allow] opt-in, with optional mTLS, message signing, and agent identity.
• Swap your MCP stack without losing your session. Hot-reload backends and config in about 8ms while the AI stays connected. No restart, no lost context.
• Production resilience. Circuit breakers, retries with backoff, rate limiting, and health checks keep one flaky server from taking down the whole toolchain.
• Dual protocol. MCP plus an A2A (agent-to-agent) transport adapter, so the same gateway routes tool calls and cross-provider agent messages.

What MCP Gateway is, and what it is not

MCP Gateway is a tool and capability router. It routes MCP tool, resource, and prompt traffic to backend MCP servers and to capability-backed REST APIs, and it can proxy MCP server-to-client requests like sampling/createMessage, elicitation/create, and roots/list back to the connected client over the existing session.

It is not a chat-completions or embeddings proxy. When a backend asks for sampling/createMessage, the connected client performs the model call, not the gateway. The OpenAI-compatible prompt-cache helpers exist for one narrow reason: so gateway_invoke can preserve prompt_cache_key behavior for backends that call LLM APIs internally. That boundary is deliberate. The value here is routing hundreds of tools through a small surface, not sitting in the model path.

Compared with the default approach of loading every tool definition into every request, the gateway trades a one-time discovery hop for a flat, small context cost. Compared with generic transport bridges that expose one server at a time, it aggregates many backends behind one namespaced surface with integrity checks, ranking, and per-user identity.

Multitenant identity

A multitenant backend (email, memory, calendar) that runs its own OIDC normally sees only "the gateway," so it cannot enforce per-user access or produce a per-user audit trail. mcp-gateway propagates the verified end-user identity to the backend through one of three configured strategies. It can mint a short-lived gateway-signed assertion, forward the caller's own token, or run an RFC 8693 token exchange for OAuth-native backends. It keeps no long-lived credential for anyone. A backend marked required fails closed rather than serve a shared key when no verified identity is present, and per-user results stay isolated in the cache. See ADR-007, ADR-008, and docs/UPGRADING-3.0.md. For the full propagation sequence, each strategy's wiring, the safety invariants, and the 2.x upgrade path, see What is new in v3.1.0: end-user identity to backends.

Independent reviews

• Five MCP hot-reload tools compared: Ruach Tov Collective's BPD-based comparison of mcp-gateway against four restart-focused alternatives, with a feature matrix and architectural analysis.
• mcp-gateway deep dive: a walkthrough of the capability system, SHA-256 integrity pinning, and the v2.5 to v2.9 development arc.

Quantitative claims in this README are sourced from docs/BENCHMARKS.md and the machine-readable benchmarks/public_claims.json, with a CI check that fails on drift. The public Trust Fabric plan is tracked in docs/roadmap/mik-6550-trust-fabric-roadmap.md.

Why the token math matters

Every MCP tool you connect costs about 150 tokens of context overhead. Connect 20 servers with 100 tools and you have burned roughly 15,000 tokens before the first message, on definitions the AI probably will not use this turn. Worse, context limits force you to choose which tools to connect at all, so the agent makes weaker decisions because the right data is out of reach.

	Without gateway	With gateway
Tools in context	Every definition, every request	17 meta-tools in the README benchmark (~1,700 tokens)
Schema footprint	~15,000 modeled tokens (100 tools)	~1,700 modeled tokens before discovery; not completed-task cost
Measured task cost	Direct path was lower at every tested size	Meta path used 1.2–16.1% more input tokens and one extra turn
Practical tool limit	20 to 50 tools under context pressure	Unlimited, discovered on demand
Connect a new REST API	Build an MCP server (days)	Drop a YAML file or import an OpenAPI spec (minutes)
Changing MCP config	Restart the AI session, lose context	Restart gateway (~8ms), session stays alive
When one tool breaks	Cascading failures	Circuit breakers isolate it

The gateway exposes 14 tools minimum, 17 in the README benchmark scenario. The base discovery quartet stays fixed; the rest are operator helpers for stats, cost, playbooks, profile control, disabled-capability visibility, and reload. Webhook status is listed only where it can answer: a deployment with a webhook registry attached, which the stdio transport never has. It costs context exactly where it is useful.

Code Mode: two tools instead of the meta-tool set

Setting code_mode.enabled: true makes tools/list return exactly two tools, gateway_search and gateway_execute, instead of the meta-tool set. Everything else is reached through those two. Tools named in meta_mcp.surfaced_tools are not appended in this mode, so the count stays at two however many backends are connected. Code Mode is off by default. gateway_search returns L0 by default (tool name, one-line purpose, score). Pass detail=l1 or detail=l2 for more, or explain=true for ranking diagnostics. include_schema=true is deprecated and maps to L2.

code_mode:
  enabled: true

Security

Connecting N MCP servers to an agent means accepting N attack surfaces. Tool poisoning, rug pulls, and exfiltration through hidden instructions in tool descriptions are demonstrated attacks, not hypotheticals. Invariant Labs' writeup (MCP Security Notification: Tool Poisoning Attacks) and Simon Willison's summary (MCP has prompt injection security problems) lay out the threat model.

mcp-gateway puts every backend tool description behind one audit surface and defends it structurally:

• Tool-poisoning validator (AX-010). Every backend tool description is scanned before it reaches the agent's context window. HIGH patterns fail closed: <IMPORTANT> blocks, ~/.ssh/~/.aws/id_rsa/.env//etc/passwd, sidenote exfiltration language, curl .* https?://, and base64 in an exfil context. MEDIUM patterns warn: 40+ consecutive spaces, zero-width or bidi-override Unicode, and oversized descriptions. Implementation: src/validator/rules/tool_poisoning.rs (19 tests).
• Optional SHA-256 capability hash-pinning. mcp-gateway cap pin <file> writes a sha256: line over the file's canonical hash (grep -v '^sha256:' capability.yaml | sha256sum reproduces it from any shell). Unpinned files still load. A pinned file that no longer matches fails closed on load and on every watcher event.
• Rug-pull detection. When a pinned capability's on-disk content changes after approval, the watcher unloads it and logs RUG-PULL DETECTED. The capability stays quarantined until an operator re-pins it. Implementation: src/capability/hash.rs and detect_rug_pulls in src/capability/backend.rs.
• Centralized audit surface. Capability YAMLs are plain text: diffable, greppable, and reviewable in a PR. The agent only ever sees the compact meta-surface, so there is no N-server tool-list pollution and no N-server attack surface.

Full walkthrough, PoC snippets, and roadmap: docs/blog/security-aware-mcp-gateway.md.

• OWASP Agentic AI Top 10 (self-assessed). Controls are mapped across all 10 ASI risks at the gateway boundary in-tree. That is not a certification. Hardening follow-ups are tracked separately for SBOMs, release signing, live remote attestation discovery, multi-gateway signing, SQL-sink defaults, and collusion detection. See docs/OWASP_AGENTIC_AI_COMPLIANCE.md.
• MITRE Fight Fraud Framework (F3). A tactic-by-tactic mapping of the same gateway-boundary controls to F3 v1.1, including the two F3-native tactics (FA0001 Positioning, FA0002 Monetization). Most cash-out and card-scheme techniques are explicit gaps. See docs/compliance/MITRE-F3-MAPPING.md.

Recent additions

• OpenAPI importer. mcp-gateway cap import <spec-url-or-file> turns an OpenAPI 3 spec into one validated capability YAML per operation. The full Swagger Petstore spec becomes 19 validated capability YAMLs end to end:

  mcp-gateway cap import https://petstore3.swagger.io/api/v3/openapi.json --output capabilities/ --prefix petstore
  

  22 tests across src/capability/openapi.rs and tests/openapi_import_tests.rs.

Architecture

flowchart TB
    subgraph GW["MCP Gateway (:39400)"]
        META["Meta-MCP surface: 14-17 tools<br/>gateway_list_servers · gateway_list_tools<br/>gateway_search_tools · gateway_invoke"]
        FS["Failsafes: circuit breaker · retry · rate limit"]
        META --> FS
    end
    FS --> B1["Tavily<br/>(stdio)"]
    FS --> B2["Context7<br/>(http)"]
    FS --> B3["Pieces<br/>(sse)"]
    FS --> B4["REST capabilities<br/>(110+)"]

Single-binary gateway. An AI client talks to the compact meta-surface, and the gateway dynamically discovers and routes to backend tools. Key modules: gateway/ (core router, OAuth, streaming, UI), provider/ (MCP/composite/capability), capability/ (discovery, validation), transport/ (HTTP, stdio), security/ (firewall, mTLS, message signing, agent identity, memory scanner), identity_propagation/, key_server/, cost_accounting/, scheduler/, skills/, tool_profiles/, config_reload/, and a2a/ (A2A transport adapter).

Features

Web dashboard

Embedded web UI at /ui: live status, searchable tools, server health, a read-only control-plane view, and a config viewer. Operator dashboard at /dashboard, which needs the admin credential — on a loopback bind serve prints a single-use link to open it with, since a browser cannot attach an Authorization header to a navigation. Cost tracking at /ui#costs. All served from the same binary and port, with no frontend build step.

Security and governance