MCP Gateway

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

MCP Gateway sits between your AI client and your tools. Instead of loading hundreds of tool definitions into every request, the AI gets 4 meta-tools and discovers the right one on demand -- like searching an app store instead of installing every app.

Public benchmark-backed claims in this README are sourced from docs/BENCHMARKS.md and the machine-readable benchmarks/public_claims.json, with CI checks to catch drift.

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.

Why not...

Quick Start

Install

Homebrew (macOS/Linux):

brew tap MikkoParkkola/tap && brew install mcp-gateway

Cargo:

cargo install mcp-gateway

Binary download:

# macOS ARM64 (M1/M2/M3/M4)
curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-darwin-arm64 -o mcp-gateway

# macOS Intel
curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-darwin-x86_64 -o 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

Docker:

docker run -v $(pwd)/gateway.yaml:/config.yaml \
  ghcr.io/mikkoparkkola/mcp-gateway:latest \
  --config /config.yaml

Configure

Create gateway.yaml:

server:
  port: 39400

meta_mcp:
  enabled: true

failsafe:
  circuit_breaker:
    enabled: true
    failure_threshold: 5
  retry:
    enabled: true
    max_attempts: 3

backends:
  tavily:
    command: "npx -y @anthropic/mcp-server-tavily"
    description: "Web search"
    env:
      TAVILY_API_KEY: "${TAVILY_API_KEY}"

  context7:
    http_url: "http://localhost:8080/mcp"
    description: "Documentation lookup"

Run

mcp-gateway --config gateway.yaml

Connect your AI client

Point your MCP client (Claude Code, Cursor, Windsurf, etc.) at the gateway:

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

That's it. Your AI now has access to all backends through 4 meta-tools. It searches for tools with gateway_search_tools and invokes them with gateway_invoke.

Key Benefits

1. Unlimited Tools, Minimal Tokens

The gateway exposes 4 meta-tools. Your AI searches for what it needs, then invokes it. Tool definitions load on demand, not upfront. Connect 500 tools and pay the token cost of 4.

Token math (Claude Opus @ $15/M input tokens, reproducible via python benchmarks/token_savings.py --scenario readme):

• Without: 100 tools x 150 tokens x 1,000 requests = 15M tokens = $225
• With: 4 meta-tools x 100 tokens x 1,000 requests = 0.4M tokens = $6

2. Any REST API to MCP Tool -- No Code

Turn any REST API into a tool by dropping a YAML file (~30 seconds) or importing an OpenAPI spec:

mcp-gateway cap import stripe-openapi.yaml --output capabilities/ --prefix stripe

The gateway ships with 70+ starter capabilities -- weather, Wikipedia, GitHub, stock quotes, package tracking, and more. Capability YAMLs hot-reload in ~500ms, no restart needed.

3. Change Your MCP Stack Without Losing Your AI Session

Your AI connects once to localhost:39400. Behind it, capability YAMLs plus reloadable gateway config sections (including backend add/remove/update and routing/profile changes) can reload live via file watching, gateway_reload_config, or POST /ui/api/reload. Listener address changes report restart_required; env_files list changes stay startup-only and take effect after restart. Your AI session stays connected.

4. Production Resilience

Circuit breakers, retry with backoff, rate limiting, health checks, graceful shutdown, and concurrency limits. One flaky server won't take down your toolchain.

Architecture

┌───────────────────────────────────────────────────────────────┐
│                    MCP Gateway (:39400)                        │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  Meta-MCP: 4 Meta-Tools + Surfaced Tools                │  │
│  │  • gateway_list_servers    • gateway_search_tools       │  │
│  │  • gateway_list_tools      • gateway_invoke             │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  Failsafes: Circuit Breaker │ Retry │ Rate Limit        │  │
│  └─────────────────────────────────────────────────────────┘  │
│                            │                                  │
│         ┌──────────────────┼──────────────────┐               │
│         ▼                  ▼                  ▼               │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐       │
│  │   Tavily    │    │  Context7   │    │   Pieces    │       │
│  │   (stdio)   │    │   (http)    │    │   (sse)     │       │
│  └─────────────┘    └─────────────┘    └─────────────┘       │
└───────────────────────────────────────────────────────────────┘

Features

Web Dashboard

Embedded web UI at /ui -- live status, searchable tools, server health, config viewer. Operator dashboard at /dashboard. Cost tracking at /ui#costs. All served from the same binary and port, no frontend build step.

Security & Governance

Integration & Discovery

Protocol & Transport

• MCP Version: 2025-11-25 (latest spec)
• Transports: stdio, Streamable HTTP, SSE, WebSocket
• Hot Reload: Capability YAMLs plus reloadable gateway config sections are watched and reloaded live
• Reload Outcomes: gateway_reload_config and /ui/api/reload return restart_required for listener changes (for example server.host / server.port); env_files list edits remain startup-only
• Config Discovery: Auto-finds gateway.yaml in cwd, ~/.config/mcp-gateway/, /etc/mcp-gateway/
• "Did You Mean?": Levenshtein-based typo correction on tool names
• Tool Annotations: MCP 2025-11-25 readOnlyHint, destructiveHint, openWorldHint
• Dynamic Descriptions: Live tool/server counts in meta-tool descriptions
• Tunnel Mode: Expose via Tailscale or pipenet without opening ports
• Shell Completions: mcp-gateway completions bash|zsh|fish
• Spec Preview (opt-in): Filtered tools/list (SEP-1821), tools/resolve (SEP-1862), dynamic promotion

Supported Backends

Any MCP-compliant server works. All three transport types supported:

API

Performance

Documentation

Troubleshooting

Backend won't connect? Test the command directly (npx -y @anthropic/mcp-server-tavily), then check gateway logs with --log-level debug.

Circuit breaker open? Check curl localhost:39400/health | jq '.backends'. Adjust thresholds in failsafe.circuit_breaker.

Tools not appearing? Verify the backend is running (gateway_list_servers). Tool lists are cached for 5 minutes.

Contributing

1. Fork and branch (git checkout -b feature/your-feature)
2. Test (cargo test) and lint (cargo fmt && cargo clippy -- -D warnings)
3. PR against main with a clear description and CHANGELOG entry

See CONTRIBUTING.md for full details. Look for good first issue or help wanted to get started.

License

MIT License -- see LICENSE for details.

Credits

Created by Mikko Parkkola. Implements Model Context Protocol version 2025-11-25.

Changelog | Releases