# @mcp-rating/gateway

[![npm](https://img.shields.io/npm/v/@mcp-rating/gateway?style=flat-square)](https://www.npmjs.com/package/@mcp-rating/gateway)
[![license](https://img.shields.io/badge/license-MIT-green?style=flat-square)](./LICENSE)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue?style=flat-square)](https://modelcontextprotocol.io)
[![tests](https://img.shields.io/badge/sandbox%20tests-18-brightgreen?style=flat-square)](./src/sandbox/sandbox.test.ts)

**Run MCP servers without handing them your API keys.**

Adding an MCP server to your client today spawns somebody else's code with your
entire environment attached — `AWS_SECRET_ACCESS_KEY`, `OPENAI_API_KEY`,
`DATABASE_URL`, everything in your shell. The gateway spawns them with a
constructed environment instead: `PATH`, `HOME`, and only the variables you or
its manifest name. Nothing else is there to read.

<!-- Absolute URL on purpose: relative image paths render on GitHub but break on
     npmjs.com, which is where anyone arriving via `npx` reads this. -->
![The same deliberately malicious MCP server, run twice: on a raw spawn it reads every
variable in the shell; through the gateway it sees fifteen, none sensitive.](https://raw.githubusercontent.com/mcprating/mcp-gateway/main/demo/sandbox-demo.gif)

| | Raw spawn (every MCP client today) | Through the gateway |
|---|---|---|
| Environment visible to the server | **your entire shell** | `PATH`, `HOME`, and what you name |
| Credentials readable | **all of them** | none |

*Reproduce it yourself in about ten seconds — `node demo/run-demo.mjs` plants two fake
credentials, reads your real environment, and prints only the count and the planted
values. Nothing of yours is displayed.*

It is also a meta-server: one entry in your config gives you the whole registry,
connected on demand rather than pre-loaded.

```json
{ "mcpServers": { "gateway": { "command": "npx", "args": ["-y", "@mcp-rating/gateway"] } } }
```

## Why it uses less of your context

Every MCP server you configure statically injects its full tool schema into
every turn, whether you use it or not. The gateway exposes 13 meta-tools at a
fixed cost and loads a server's tools only once you connect to it.

| | measured |
|---|--:|
| Median real MCP server | **2,587 tokens** |
| 10 servers configured statically | **~25,900 tokens, every turn** |
| Gateway, flat | **2,644 tokens** |

Roughly **10× less** standing overhead at ten servers, and the gap widens with
each one you add. One median server already costs about what the entire gateway
costs.

### But standing overhead is not the bill — here is the break-even

That 10× is what *sits* in the window. It is not what a conversation costs,
because the gateway also adds turns: it has to discover a server and connect to
it before using it, every turn re-sends the whole transcript, and `mcp_discover`
output stays in that transcript afterwards.

Measured end to end on gemma-4-31B through vLLM, with the server's own tokenizer
rather than an estimate:

| | tokens | turns |
|---|--:|--:|
| Gateway, cold — discover, connect, then call a tool | **17,904** | 5 |
| Same tool call, server already configured | **6,605** | 2 |

**With one server, the gateway costs 2.7× more than just configuring it.** The
saving only appears once you have enough servers that carrying all their schemas
outweighs the setup. N configured, one actually used, after ten turns of work:

| servers | static | gateway | |
|--:|--:|--:|---|
| 1 | 25,870 | 70,524 | static wins 2.7× |
| 2 | 51,740 | 70,524 | static wins 1.4× |
| **4** | 103,480 | 70,524 | gateway wins 1.5× |
| 10 | 258,700 | 70,524 | gateway wins 3.7× |
| 20 | 517,400 | 70,524 | gateway wins 7.3× |

**Break-even is three to five servers.** Below that, a hand-written config is
genuinely cheaper and you should use one. Above it the gateway wins, and keeps
winning as you add more — but the honest figure at ten servers is about **3×**
on total tokens, not the 10× you get by counting standing overhead alone.

*Honest about the method:* measured from the tool schemas of 91 servers this
project has connected to and introspected — drawn from the 300 most-downloaded
in the registry — summing `{name, description, inputSchema}` per tool, the
payload a client actually receives from `tools/list`, sized as `chars / 4`. That
is an estimate, not a tokenizer.

**Median, not mean, and the distribution is why.** The mean is 9,965 tokens,
dragged there by a long tail: 19 of the 91 cost over 10,000 tokens and the
heaviest — a Spotify server exposing 608 tools — costs 135,666, about 68% of a
200k context window on its own. Quoting the mean would flatter this project's
numbers using servers almost nobody installs.

The saving is real precisely because most configured servers sit unused in most
conversations — but see the break-even above before assuming it applies to you.

The `chars / 4` estimate was checked against three real tokenizers and came in at
0.88×, 0.98× and 1.01× of the true count, so it never reads low.

Reproduce both: `node demo/shorts/short2-context.mjs --refresh` for the schema
corpus, and `demo/ollama-probe.mjs` for the end-to-end bill —

```bash
# gateway cold: must discover and connect first
OLLAMA_HOST=http://host:8000/v1 node demo/ollama-probe.mjs your-model

# baseline: server already attached, like a static config
PRECONNECT=everything-slim OLLAMA_HOST=... node demo/ollama-probe.mjs your-model
```

## How It Works

```
┌────────────────────┐       ┌──────────────┐       ┌──────────────────┐
│  Claude Desktop /  │ stdio │              │ stdio  │ MCP Server A     │
│  Cursor / Windsurf │◄─────►│  MCP Gateway │◄──────►│ (e.g. filesystem)│
│  (host client)     │       │              │◄──┐    └──────────────────┘
└────────────────────┘       └──────────────┘   │    ┌──────────────────┐
                                    │           └───►│ MCP Server B     │
                                    ▼                │ (e.g. github)    │
                             ┌──────────────┐        └──────────────────┘
                             │ MCP-Rating   │
                             │ Registry API │
                             └──────────────┘
```

Instead of manually configuring each MCP server in your client, the Gateway:

1. **Discovers** servers via the MCP-Rating registry
2. **Connects** to them on-demand (spawns as child processes)
3. **Proxies** their tools through namespaced names (`servername__toolname`)
4. **Notifies** your client when tools are added/removed

## Quick Start

### With Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gateway": {
      "command": "npx",
      "args": ["-y", "@mcp-rating/gateway"]
    }
  }
}
```

Then ask Claude:
- *"Search for MCP servers that work with databases"* (uses `mcp_discover`)
- *"Connect to the sqlite server"* (uses `mcp_connect`)
- *"Query my database"* (calls the proxied tool directly)

### Cursor

`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "gateway": { "command": "npx", "args": ["-y", "@mcp-rating/gateway"] }
  }
}
```

### Claude Code

```bash
claude mcp add gateway -- npx -y @mcp-rating/gateway
```

### Windsurf

`~/.codeium/windsurf/mcp_config.json`, same shape as Cursor:

```json
{
  "mcpServers": {
    "gateway": { "command": "npx", "args": ["-y", "@mcp-rating/gateway"] }
  }
}
```

### Any other MCP client

```json
{ "command": "npx", "args": ["-y", "@mcp-rating/gateway"] }
```

Restart the client after editing its config — most read it only at startup.

## Meta-Tools

The gateway exposes 13 built-in tools:

| Tool | Description |
|------|-------------|
| `mcp_discover` | Search the MCP-Rating registry for MCP servers |
| `mcp_connect` | Connect to a server and make its tools available |
| `mcp_disconnect` | Disconnect a server and remove its tools |
| `mcp_list_active` | List connected servers and their tools |
| `mcp_server_info` | Detailed info about a server, from the registry or a live connection |
| `mcp_call_tool` | Call a tool on a connected server |
| `mcp_gateway_health` | Diagnostics: version, uptime, connection and registry status |
| `mcp_sandbox` | View or customise a server's sandbox manifest (env/network/filesystem) |
| `mcp_audit` | The safety audit trail — what sandboxed servers actually did |
| `mcp_profiles` | Named connection profiles (work, personal, …) |
| `mcp_groups` | Atomic connect/disconnect of server sets |
| `mcp_usage` | Call counts, latency and error rates for connected servers |
| `mcp_recommend` | Server recommendations based on usage |

## Trust Tiers

Every connected server is labeled with a trust tier based on its MCP-Rating quality score:

- **[Verified]** — High quality + officially verified
- **[Trusted]** — Good quality with repository and install command
- **[Community]** — Listed in registry with basic quality
- **[Unverified]** — Unknown origin (manually connected)

## Configuration

The gateway reads config from `~/.mcp-gateway/config.json`:

```json
{
  "registryApiUrl": "https://mcprating.io/api/v1",
  "proxyTimeoutMs": 30000,
  "maxConnections": 10,
  "logLevel": "info"
}
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_GATEWAY_REGISTRY_URL` | MCP-Rating API base URL | `https://mcprating.io/api/v1` |
| `MCP_GATEWAY_TIMEOUT` | Proxy timeout (ms) | `30000` |
| `MCP_GATEWAY_MAX_CONNECTIONS` | Max simultaneous connections | `10` |
| `MCP_GATEWAY_LOG_LEVEL` | Log level (debug/info/warn/error) | `info` |
| `MCP_GATEWAY_CONTAINER_ISOLATION` | Force L2 container isolation on/off | manifest decides |
| `MCP_GATEWAY_AUDIT_LOG` | Path for the forensic audit log | disabled |
| `MCP_GATEWAY_PARTNER_KEY` | Partner attribution key — **enables ad telemetry** | unset |
| `MCP_GATEWAY_AD_TRACKING` | Set to `false` to disable ad telemetry outright | unset |
| `MCP_GATEWAY_HTTP_TOKEN` | Bearer token for HTTP daemon mode | unset |

## Security model

The gateway exists because plain MCP hands every server your whole environment.
Two layers push back, and it is worth being precise about what each one does and
does not do.

### L1 — environment scoping (always on, for stdio servers)

A downstream server receives `PATH`, `HOME` and friends, plus only the variable
**names** its manifest allowlists or you pass at connect time. Everything else in
the parent environment — `AWS_*`, `OPENAI_API_KEY`, `DATABASE_URL` — is withheld.
Exported shell functions (`BASH_FUNC_*`) are dropped rather than forwarded.

This is genuine enforcement: the child process is spawned with a constructed
environment, so there is nothing to opt out of or bypass.

### L2 — container isolation (opt-in)

When a manifest requests it, or `MCP_GATEWAY_CONTAINER_ISOLATION=true`, the
server runs under `docker`/`podman` with an ephemeral container.

### Network allowlists: read this before relying on them

`network: "allowlist"` starts an in-process forward proxy and points the child at
it via `HTTP_PROXY`/`HTTPS_PROXY`.

**This filters proxy-aware clients only.** Node's fetch/undici, axios, and Python
requests all honour those variables, which covers most real servers. A program
that opens raw TCP sockets, or a compiled binary that ignores proxy environment
variables, **is not filtered**. Treat allowlists in L1 as a guard rail against
honest code, not a containment boundary against hostile code — for that you need
L2 with container network namespacing.

Allowlist patterns fail **closed**: a malformed pattern such as `*example.com`
(missing dot) matches nothing rather than everything. The gateway warns at
startup about patterns that will not do what their author intended, including
over-broad ones like `*.com`.

### What is not covered

If the host client is `SIGKILL`ed, the gateway cannot run its shutdown path and
spawned child processes may be left behind. `SIGINT`/`SIGTERM` are handled and
disconnect everything cleanly; `SIGKILL` is untrappable by definition.

## Telemetry

**Off unless you turn it on.** The ad tracker is constructed only when
`MCP_GATEWAY_PARTNER_KEY` is set — with no partner key there is no partner
telemetry, and nothing is posted about your connects or tool calls.

If a partner key is set (you are earning attribution revenue), connect and
tool-execution events are sent to mcprating.io. Disable it while keeping the key
with `MCP_GATEWAY_AD_TRACKING=false`.

Separately, the gateway calls the MCP-Rating registry API for `mcp_discover` and
`mcp_recommend` — that is the lookup you asked for, not background reporting.
Usage analytics (`mcp_usage`) are an in-memory ring buffer and never leave the
process.

## Development

```bash
npm install
npm run dev        # watch mode
npm run typecheck
npm run build
npm test           # sandbox unit tests (env scoping + egress allowlist)
```

## Architecture

The gateway is built on the [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) and uses:

- **StdioServerTransport** — communicates with the host client
- **StdioClientTransport** — spawns and communicates with downstream servers
- **Dynamic tool registration** — `McpServer.registerTool()` + `sendToolListChanged()`
- **Tool namespacing** — `slug__toolname` pattern prevents collisions
- **Passthrough Zod schemas** — preserves parameter names for host client UI while letting downstream servers validate

## License

MIT — see [LICENSE](./LICENSE).

---

If this saved you from handing your keys to a stranger's code, a ⭐ helps other people
find it.