MCP Gateway Overview

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 setups have a fundamental scaling problem: every terminal spawns its own server processes. With 7 terminals using 4 MCP servers each, you end up with 28 running processes consuming over 1GB of RAM.

Even worse, each message sent to the AI includes the full list_tools response from every server—often 20,000+ tokens of tool definitions sent repeatedly, whether you use those tools or not.

The Solution

MCP Gateway solves both problems:

• Process Sharing: All terminals connect to one gateway, which routes requests to shared backend processes. 7 terminals → 4 shared servers instead of 28.
• Lazy Tool Loading: Tool definitions are only sent when you actually use a tool. Messages without tool calls send zero overhead.
• Smart Scoping: Servers can be scoped globally (shared by all), per-workspace (isolated by project), or per-credential (isolated by auth tokens).

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Terminal 1  │     │ Terminal 2  │     │ Terminal 3  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                    ┌──────▼──────┐
                    │ MCP Gateway │  ← Single entry point
                    │   :8989     │
                    └──────┬──────┘
                           │
       ┌───────────────────┼───────────────────┐
       │                   │                   │
┌──────▼──────┐     ┌──────▼──────┐     ┌──────▼──────┐
│  Context7   │     │  Supabase   │     │ Filesystem  │
│  (global)   │     │ (workspace) │     │  (global)   │
└─────────────┘     └─────────────┘     └─────────────┘

Key Benefits

Hot Reload

The gateway watches configuration files and automatically reloads when they change. This means:

• 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. Adding 10 servers to your config doesn't spawn 10 processes.

Environment Variables

Many MCP servers require API keys or tokens. The gateway supports environment variable substitution in two ways:

1. Global Config File

Define variables directly in ~/.mcp-gateway/config.yaml:

servers:
  github:
    command: npx
    args: [-y, "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"  # References system env var

2. Project-Level .env Files

For workspace-scoped servers, place a .env file at your project root:

# /my-project/.env
SUPABASE_PROJECT_REF=abc123xyz
SUPABASE_ACCESS_TOKEN=sbp_xxxxxxxxxxxxx
GITHUB_TOKEN=ghp_xxxxxxxxxxxxx

The gateway automatically resolves these based on the cwd context passed with each request. Different projects can use different credentials for the same server.

Resolution Order

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 with exponential backoff.
• Circuit breaker: After repeated failures, servers are temporarily disabled to prevent cascade failures. They're re-enabled after a cooldown period.
• Graceful shutdown: When the gateway stops, it sends SIGTERM to all backend processes and waits for clean shutdown before exiting.

Supported Server Types

See Server Types for detailed configuration examples.

Next Steps

• HTTP API — Request/response format and methods
• Configuration — Add MCP servers to your gateway
• CLI Reference — All available commands
• Scoping — Global vs workspace vs credential isolation
• Admin Panel — Web UI for monitoring and management