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:

Tool	What it does
gateway_list_servers	Shows available servers and their status
gateway_load_server	Connects to a server and discovers its tools
gateway_call_tool	Calls a tool on a connected server
gateway_reload_server	Reconnects a server (picks up code changes)

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

Field	Required	Default	Description
type	No	stdio	Transport: stdio, http, sse, or streamable-http
command	Yes (stdio)	-	Command to run the server
args	No	[]	Command arguments
env	No	{}	Environment variables
url	Yes (http)	-	Server URL
headers	No	{}	HTTP headers (auth tokens, etc.)
timeout	No	30/60	Request timeout in seconds (30 for stdio, 60 for http)
description	No	-	Human-readable description shown in gateway_list_servers

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.

	MCP Gateway	RTK
Problem	Tool schemas from idle MCP servers waste context	Verbose CLI output wastes context
How	Lazy-loads servers, exposes 4 proxy tools	Compresses command output before it hits context
When	Startup / tool registration	Runtime / command execution
Scope	MCP server management	Shell commands (git, npm, cargo, etc.)

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

Requirements

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

License

MIT