MCP Gateway

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

Permitted noncommercial and nonprofit use is free, including running the full gateway. Commercial use outside these free permissions 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 (Claude, Cursor, ...)"] subgraph GW["MCP Gateway (single binary)"] META["Compact meta-surface 9-17 tools"] DISC{"Discover on demand gateway_search_tools gateway_invoke"} end T1["MCP backend Tavily (stdio)"] T2["MCP backend Context7 (http)"] C1["REST capability GitHub"] C2["REST capability Stripe"] Cn["110+ capabilities"]

AI -->|"9-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 11 tools instead of ~150 — 11 is the default HTTP configuration counted for an administrator; an ordinary client is shown four fewer. 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

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.

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; 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 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 # restore one client config

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

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

Manual JSON snippet (if you prefer to edit by hand)

{

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

Why use MCP Gateway?

• **Larger catalog,