MCP Gateway

A lazy-loading proxy that sits between Claude and your MCP servers. Instead of loading every server at startup (which dumps hundreds of tool schemas into context and burns tokens), the gateway exposes just 4 lightweight tools. Backend servers only start when you actually need them.

Before: 10 MCP servers = 200+ tool schemas loaded into every conversation = thousands of wasted tokens.

After: 10 MCP servers behind the gateway = 4 tool schemas loaded. Each server starts on demand.

The Problem

Every MCP server you add to Claude Code registers all its tools upfront. A typical server has 10-30 tools, each with a full JSON schema. With 10 servers that's 100-300 tool definitions eating your context window before you even ask a question.

Most conversations only use 1-2 servers. The rest are dead weight.

How It Works

The gateway exposes 4 tools to Claude:

When Claude needs a server, it calls gateway_load_server. The gateway starts the subprocess, does the MCP handshake, and caches the connection. Subsequent calls reuse the running process.

Servers that aren't used never start. No tokens wasted.

Quick Start

git clone https://github.com/raiansar/mcp-gateway.git
cd mcp-gateway
./install.sh

Edit config.json to add your servers, then add the gateway to Claude Code:

claude mcp add gateway -- /path/to/mcp-gateway/run.sh

That's it. All your servers are now behind a single gateway.

Configuration

config.json is a simple map of server names to their connection details. The gateway supports both stdio (local processes) and HTTP (remote servers) transports.

Stdio Servers (local)

{
  "servers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "some-mcp-server@latest"],
      "env": {
        "API_KEY": "your-key"
      },
      "timeout": 30,
      "description": "What this server does"
    }
  }
}

HTTP Servers (remote)

{
  "servers": {
    "remote-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      },
      "timeout": 60,
      "description": "Remote MCP server"
    }
  }
}

Python Servers (uv)

{
  "servers": {
    "my-python-server": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/server", "server-name"],
      "env": {},
      "timeout": 120,
      "description": "Python server managed by uv"
    }
  }
}

Config Fields

Migrating Your Existing MCP Servers

If you already have MCP servers configured in Claude Code, move them to the gateway:

Before (in ~/.claude.json or Claude Desktop config):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
    },
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": { "TAVILY_API_KEY": "tvly-xxx" }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "env": {}
    }
  }
}

After (in config.json):

{
  "servers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" },
      "description": "GitHub - repos, issues, PRs, code search"
    },
    "tavily": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": { "TAVILY_API_KEY": "tvly-xxx" },
      "description": "Tavily AI search"
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "env": {},
      "description": "File system access"
    }
  }
}

Then remove the individual servers from Claude and add just the gateway:

claude mcp remove github -s user
claude mcp remove tavily -s user
claude mcp remove filesystem -s user
claude mcp add gateway -- /path/to/mcp-gateway/run.sh

Usage

Once configured, Claude automatically uses the gateway. A typical interaction:

1. Claude calls gateway_list_servers to see what's available
2. Claude calls gateway_load_server("github") when it needs GitHub
3. Claude calls gateway_call_tool("github", "search_repositories", '{"query": "mcp"}') to use a tool
4. The GitHub server stays running for subsequent calls in the same session

The description field in your config helps Claude decide which server to load for a given task, so write good descriptions.

How This Differs from RTK

RTK is a CLI proxy that compresses shell command output (git, ls, test runners, etc.) to reduce token consumption by 60-90%.

MCP Gateway solves a different problem: it prevents MCP tool schema bloat by lazy-loading servers on demand instead of registering all tools upfront.

They're complementary. Use both for maximum token savings.

Requirements

• Python 3.10+
• mcp package (installed by install.sh)

License

MIT