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 |
| Project-Aware Credentials | Each project'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
The gateway watches configuration files and automatically reloads when they change:
- 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. Run mcpg install playwright in another terminal, and within seconds the browser automation tools are available in your current session—without restarting anything.
Environment Variables
The gateway supports per-project credentials through .env files:
# /my-project/.env
SUPABASE_PROJECT_REF=abc123xyz
SUPABASE_ACCESS_TOKEN=sbp_xxxxxxxxxxxxx
GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
Different projects 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-project/.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-project 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