Overview
Stop spawning. Start sharing.
MCP Gateway is a process-sharing layer that sits between your AI client (Claude Code, Cursor, etc.) and your MCP servers. Instead of each terminal spawning its own server processes, all terminals share a single set of backend processes through the gateway.
The Problem
Traditional MCP spawns separate server processes per terminal:
Terminal 1 → github (50MB) + supabase (60MB) + filesystem (40MB)
Terminal 2 → github (50MB) + supabase (60MB) + filesystem (40MB)
Terminal 3 → github (50MB) + supabase (60MB) + filesystem (40MB)
─────────────────────────────────────────────────────────────────
Total: 9 processes consuming 450MB RAM
With 10-15 terminals across multiple workspaces, that's 30-45 separate Node processes eating RAM.
The Solution
MCP Gateway shares server processes across all terminals:
Terminal 1 ─┐
Terminal 2 ─┼──→ MCP Gateway (20MB) ──→ github (50MB)
Terminal 3 ─┘ │ supabase (60MB)
└──────────────→ filesystem (40MB)
─────────────────────────────────────────────────────────────────
Total: 4 processes consuming 170MB RAM (62% reduction)
Scale it up: 20 terminals × 5 servers = 100 processes → just 6 processes. That's 94% fewer processes.
Features
| Feature | Description |
|---|---|
| Hot Configuration | Add/remove servers without restarting your AI session |
| Workspace-Aware Credentials | Each workspace's .env isolates its API keys |
| Lazy Tool Discovery | Tools load on-demand, saving context tokens |
| Intelligent Process Sharing | Servers shared globally, per-workspace, or per-credential |
| Flexible Auth | Bearer tokens, API keys, or localhost trust |
| Scope Protection | Global config changes require explicit confirmation |
| Instant Availability | New servers available immediately—no restart required |
| Self-Healing | Crashed servers auto-restart with exponential backoff |
Key Benefits
| Metric | Traditional | With Gateway | Improvement |
|---|---|---|---|
| Processes (7 terminals) | 28 | 4-6 | ↓ 78% |
| Memory usage | ~1.1 GB | ~235 MB | ↓ 79% |
| Tokens per message | ~67,500 | ~800 | ↓ 99% |
| Startup (new terminal) | 2-4 sec | <100ms | ↓ 95% |
Architecture
Process sharing modes:
- Global — Single instance shared by all terminals (Context7)
- Per-workspace — One instance per project directory (Supabase)
- Per-credential — One instance per unique API token (GitHub)
Hot Configuration
Configuration changes are picked up automatically on the next request:
- Instant availability: Add a new server to your config and it's immediately available to all connected terminals—no restart required.
- No session interruption: Existing terminal sessions continue working while new servers come online.
- Lazy spawning: Server processes aren't started until you actually use a tool from that server.
You're in the middle of a Claude Code session and realize you need the Playwright MCP server. Install it, and within seconds the browser automation tools are available in your current session—without restarting anything:
install_server(server="playwright", scope="global")
Environment Variables
The gateway supports per-workspace credentials through .env files:
# /my-workspace/.env
SUPABASE_PROJECT_REF=abc123xyz
SUPABASE_ACCESS_TOKEN=sbp_xxxxxxxxxxxxx
GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
Different workspaces can use different credentials for the same server. The gateway resolves credentials based on the cwd context passed with each request.
Resolution Order
| Priority | Source | Example |
|---|---|---|
| 1 (highest) | Workspace .env file | /my-workspace/.env |
| 2 | Gateway .env file | ~/.mcp-gateway/.env |
| 3 | Profile env: block | Inline values in config.yaml |
| 4 (lowest) | System environment | export GITHUB_TOKEN=xxx |
Workspace .env files override gateway defaults, allowing shared credentials with per-workspace overrides.
Never commit .env files to version control. Add .env to your .gitignore.
Process Lifecycle
Backend server processes are managed automatically:
- Lazy start: Processes spawn on first tool call, not at gateway startup.
- Health monitoring: The gateway checks process health and automatically restarts crashed servers.
- Exponential backoff: Failed restarts wait progressively longer to prevent thrashing.
- Circuit breaker: After repeated failures, servers are temporarily disabled.
- Graceful shutdown: SIGTERM to all backend processes with clean shutdown wait.
Supported Server Types
| Type | Description | Example |
|---|---|---|
| HTTP | Pre-hosted MCP servers with HTTP endpoints | Supabase MCP, Context7 |
| stdio | Local processes communicating via stdin/stdout | Filesystem, GitHub MCP |
| Docker | Containerized servers for isolation | Custom servers, sandboxed tools |
See Server Types for detailed configuration examples.
Next Steps
- Installation — Get started in 3 commands
- Configuration — Add MCP servers to your gateway
- Agent Integration — Gateway tools for AI agents
- Scoping — Global vs workspace vs credential isolation