Mcp Gateway

MCP Gateway

[](https://github.com/MikkoParkkola/mcp-gateway/actions/workflows/ci.yml) [](https://crates.io/crates/mcp-gateway) [](https://crates.io/crates/mcp-gateway) [](https://www.rust-lang.org) [](https://github.com/MikkoParkkola/mcp-gateway/blob/main/LICENSE) [](https://github.com/rust-secure-code/safety-dance/) [](https://deps.rs/repo/github/MikkoParkkola/mcp-gateway) [](https://github.com/MikkoParkkola/mcp-gateway/tree/main/capabilities) [](https://modelcontextprotocol.io) [](docs/OWASPAGENTICAI_COMPLIANCE.md) [](https://glama.ai/mcp/servers/MikkoParkkola/mcp-gateway) [](https://glama.ai/mcp/servers/MikkoParkkola/mcp-gateway) [](https://insiders.vscode.dev/redirect/mcp/install?name=mcp-gateway&config=%7B%22command%22%3A%22mcp-gateway%22%2C%22args%22%3A%5B%22serve%22%2C%22--stdio%22%5D%7D) [](cursor://anysphere.cursor-deeplink/mcp/install?name=mcp-gateway&config=%7B%22command%22%3A%22mcp-gateway%22%2C%22args%22%3A%5B%22serve%22%2C%22--stdio%22%5D%7D)

Give your AI access to every tool it needs -- without burning your context window or building MCP servers.

Independent Reviews

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

MCP Gateway sits between your AI client and your tools. Instead of loading hundreds of tool definitions into every request, the AI gets a compact Meta-MCP surface -- 14 tools minimum, 16 in the README benchmark scenario, 17 when webhook status is surfaced -- and discovers the right backend tool on demand.

Public quantitative claims in this README are sourced from [docs/BENCHMARKS.md](docs/BENCHMARKS.md) and the machine-readable [benchmarks/publicclaims.json](benchmarks/publicclaims.json), with CI checks to catch drift.

What MCP Gateway is / is not

MCP Gateway is a tool and capability gateway. It routes MCP tool/resource/prompt traffic to backend MCP servers and 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 gateway session.

MCP Gateway is not a general OpenAI/Anthropic chat completions or embeddings gateway. When a backend asks for sampling/createMessage, the connected client still performs the model call. The OpenAI-compatible prompt-cache helpers in the gateway exist only so gateway_invoke can preserve prompt_cache_key behavior for backends or capabilities that happen to call LLM APIs internally.

Why

The context window is the bottleneck. Every MCP tool you connect costs ~150 tokens of context overhead. Connect 20 servers with 100+ tools and you've burned 15,000 tokens before the conversation starts -- on tool definitions the AI probably won't use this turn.

Worse: context limits force you to choose which tools to connect. You leave tools out because they don't fit -- and your AI makes worse decisions because it can't reach the right data.

MCP Gateway removes that tradeoff entirely.

| | Without Gateway | With Gateway | |---|----------------|--------------| | Tools in context | Every definition, every request | 16 Meta-MCP tools in the README benchmark (~1600 tokens) | | Token overhead | ~15,000 tokens (100 tools) | ~1600 tokens -- 89% savings | | Cost at scale | ~$0.22/request (Opus input) | ~$0.024/request -- $201 saved per 1K | | Practical tool limit | 20-50 tools (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 AI session, lose context | Restart gateway (~8ms), session stays alive | | When one tool breaks | Cascading failures | Circuit breakers isolate it |

The base discovery quartet (gateway_list_servers, gateway_list_tools, gateway_search_tools, gateway_invoke) stays constant. The README benchmark scenario also surfaces stats, cost report, playbooks, profile controls, disabled-capability visibility, and reload for a 15-tool surface. Surfacing webhook status adds the 16th tool.

Why not...

| Alternative | What it does | Why MCP Gateway is different | |---|---|---| | Direct MCP connections | Each server connected individually | Every tool definition loaded every request. 100 tools = 15K tokens burned. Gateway: a small fixed 13-16 tool surface instead of every backend tool. | | Claude's ToolSearch | Built-in deferred tool loading | Only works with tools already configured. Gateway adds unlimited backends + REST APIs without MCP servers. | | Archestra | Cloud-hosted MCP registry | Requires cloud account, sends data to third party. Gateway is local-only, zero external dependencies. | | Kong / Portkey | General API gateways | Not MCP-aware. No meta-tool discovery, no tool search, no capability YAML system. | | Building fewer MCP servers | Reduce tool count manually | You lose capabilities. Gateway lets you keep everything and pay the token cost of the compact Meta-MCP surface. |

vs Anthropic MCP Tunnels

On 2026-05-19 Anthropic shipped Claude Managed Agents with self-hosted sandboxes (public beta) and MCP tunnels (research preview). MCP tunnels let a Claude agent reach a single MCP server inside a private network through one outbound connection from a lightweight gateway -- no inbound firewall rules, no public endpoint, encrypted end-to-end.

mcp-gateway and Anthropic's MCP tunnel sit at different layers and compose. The tunnel is reachability plumbing for one private MCP server. mcp-gateway is the aggregation, routing, capability-namespacing and observability layer across many MCP and REST backends. When both are deployed, mcp-gateway becomes the private MCP server that Anthropic's tunnel exposes -- one tunnel, one outbound connection, every backend behind it.

| Concern | Anthropic MCP tunnel | mcp-gateway | Boundary | |---|---|---|---| | Backend topology | Single MCP server per tunnel, exposed through one outbound connection (overview) | N-backend aggregation: 110+ REST capabilities + multiple MCP backends behind a compact 14-16 tool Meta-MCP surface (src/gateway/, capabilities/*.yaml) | Different primitive: 1-server reachability vs many-backend aggregation | | Tool routing | Opaque pass-through; the agent sees whatever tool list the tunneled server publishes | Capability namespacing + dynamic gateway_search_tools / gateway_invoke discovery (src/gateway/); SHA-256 pinning per capability (src/capability/hash.rs) | Different layer: transport reachability vs tool-surface curation and integrity | | Observability | Per-tunnel session telemetry from Anthropic's side | Unified trace_id and cost-accounting across every backend invocation (src/cost_accounting/, src/gateway/) | Scope distinction: per-tunnel session vs cross-backend trace correlation |

Complementary, not a replacement. A team that wants Claude Managed Agents to reach a private-network deployment of mcp-gateway uses the tunnel for reachability and mcp-gateway for fan-out, capability hygiene, OWASP Agentic AI controls ([docs/OWASPAGENTICAICOMPLIANCE.md](docs/OWASPAGENTICAICOMPLIANCE.md)), and unified cost / trace telemetry. The two solve adjacent problems.

Security

Connecting N MCP servers to an agent means accepting N attack surfaces. Tool poisoning, rug pulls, and exfiltration via 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: ` blocks, ~/.ssh/~/.aws/idrsa/.env//etc/passwd, sidenote exfiltration language, curl .* https?://, base64 in exfil context. MEDIUM patterns warn: 40+ consecutive spaces, zero-width / bidi-override Unicode, oversized descriptions. Implementation: [src/validator/rules/toolpoisoning.rs`](src/validator/rules/tool_poisoning.rs) (19 tests).
• SHA-256 capability hash-pinning. mcp-gateway cap pin writes a sha256: line over the file's canonical hash (grep -v '^sha256:' capability.yaml | sha256sum is reproducible from any shell). The loader refuses any mismatched file 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. Implementation: [src/capability/hash.rs](src/capability/hash.rs) and detect_rug_pulls in [src/capability/backend.rs](src/capability/backend.rs).
• Centralized audit surface. Capability YAMLs are plain text, diffable, grep-able, PR-reviewable. The agent only ever sees the compact Meta-MCP surface (13-16 tools). No N-server tool-list pollution means no N-server attack surface.

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

• OWASP Agentic AI Top 10. Controls are mapped across all 10 risks, with explicitly tracked partial/out-of-scope gaps for multi-gateway signing, tool-result sandboxing, collusion detection, and remote-server provenance. See [docs/OWASPAGENTICAICOMPLIANCE.md](docs/OWASPAGENTICAICOMPLIANCE.md).

Recent additions

• OpenAPI importer. mcp-gateway cap import 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:

``bash mcp-gateway cap import https://petstore3.swagger.io/api/v3/openapi.json --output capabilities/ --prefix petstore ` 22 tests across [src/capability/openapi.rs](src/capability/openapi.rs) and [tests/openapiimporttests.rs`](tests/openapiimporttests.rs).

Quick Start

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. Works in Claude Code, Cursor, Windsurf, Codex, and any AI with terminal access.

Or 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's 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.

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.yaml:/config.yaml ghcr.io/mikkoparkkola/mcp-gateway:latest --config /config.yaml |

Direct binary download

# 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; and writes the gateway entry back into each detected client config so they route through the gateway instead. 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 claude mcp add / codex mcp add compatible:

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's configured. mcp-gateway remove removes one.

Option C — Hand-write gateway.yaml

For the full schema reference, see [docs/QUICKSTART.md#configuration](docs/QUICKSTART.md#configuration). Minimal example:

server:
  port: 39400

meta_mcp:
  enabled: true

backends:
  tavily:
    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 once serve is running.

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                 # all detected clients
mcp-gateway setup export --target claude-code         # one client
mcp-gateway setup export --target all --dry-run       # preview without writing
mcp-gateway setup export --target all --watch         # regenerate on gateway.yaml changes

| 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) | | `z

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MikkoParkkola
• Source: MikkoParkkola/mcp-gateway
• License: MIT
• Homepage: https://crates.io/crates/mcp-gateway

Install and usage instructions live in the source repository linked above.