# 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:

| 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

```bash
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:

```bash
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)

```json
{
  "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)

```json
{
  "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)

```json
{
  "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):
```json
{
  "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`):
```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:

```bash
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](https://github.com/rtk-ai/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