# @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)

**Run MCP servers without handing them the API keys in your environment.**

Whether a server you add can read your environment (`AWS_SECRET_ACCESS_KEY`,
`OPENAI_API_KEY`, `DATABASE_URL`) depends on how your client starts it. The
official MCP SDKs pass a short allowlist by default: `HOME`, `PATH`, `USER` and a
few more. A client or script that passes its whole environment, often just to
forward the one token a server needs, hands over everything. We haven't yet
measured which popular clients do which, so we don't name any. The gateway
doesn't leave it to the client: it spawns every server with a constructed
environment, the SDK's short allowlist (`PATH`, `HOME`, `USER` and a few
more) plus only the variables you or its manifest name. Nothing else from your
environment is there to read.

**Files are a different matter.** By default a server still runs as you, so it
can read what you can — `~/.ssh`, `~/.aws/credentials`, a project's `.env`. Only
container isolation (opt-in, needs Docker) closes that. See
[what each level protects](#security-model).

<!-- 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: started with the whole
environment it steals four planted fake credentials; through the gateway it sees fifteen
variables, none sensitive.](https://raw.githubusercontent.com/mcprating/mcp-gateway/main/demo/sandbox-demo.gif)

| | Started with the whole environment | Through the gateway |
|---|---|---|
| Environment visible to the server | **everything the client had** | a short allowlist (`PATH`, `HOME`, `USER` and a few more), and what you name |
| Credentials in environment variables | **all of them** | none you didn't name |
| Credential files (`~/.ssh`, `~/.aws`, `.env`) | readable | **still readable**, unless container isolation is on |

*Reproduce it yourself in about ten seconds: `node demo/run-demo.mjs` plants two fake
credentials and runs the server both ways. It prints the planted values in full and,
for anything real it finds in your environment, only the variable's name, never its
value. The GIF is generated by `node demo/render-gif.mjs` from a clean, synthetic
environment, so it shows nothing from any real machine.*

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, listing first the ones it can
   start right now (see below)
2. **Connects** to them on-demand: spawns local ones as child processes, and
   connects hosted ones to the endpoint the registry lists
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.

## What `mcp_discover` puts first

An agent can only use a server the gateway can start, so results are ordered by
that, keeping relevance order within each group:

1. **Verified**: the registry's own harness started it and it listed its tools
   (`✓ Started in our test`).
2. **Ready, untested**: installable here, or a hosted endpoint that needs no
   header, and any key it declares is set.
3. **Needs setup**: a declared key isn't set, its launcher (`uvx`, `docker`) isn't
   installed, or the hosted endpoint needs a header the gateway can't send yet.
4. **Failed in our test**: it didn't start when the registry tried it, with no
   credentials (`✗ Didn't start in our test`).
5. **Can't start by slug**: no install command and no endpoint recorded.

"Verified" means it started and listed tools, not that every tool works without
a key. The harness supplies none. Most of the index has never been tried; that
says nothing either way.

## Meta-Tools

The gateway exposes 13 built-in tools:

| Tool | Description |
|------|-------------|
| `mcp_discover` | Search the MCP-Rating registry; servers the gateway can start now come first |
| `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 an install command or a remote endpoint
- **[Community]** — Listed in registry with basic quality
- **[Unverified]** — A package MCP Rating doesn't know, from any registry or started by command

A safety score in the risk band caps the tier, as it does on the site: below 50
a server is at most [Community], below 30 it is [Unverified].

### What `mcp_connect` shows, and when it asks first

Before anything starts, `mcp_connect` looks up what MCP Rating knows about the
package that would run — from the registry entry, or, for an explicit `command`
or `url`, from the package itself (`npx pkg`, `uvx pkg`, `docker run image`,
the endpoint). A known package started by command is judged as itself, not as
[Unverified]. Shown in the confirmation and again once connected:

- score and trust tier, with the server's page;
- safety score and each flag with its reason;
- MCP Rating's own start test: started, didn't start, needs credentials, or not tested;
- last release and last code push, with where each date comes from.

It asks for confirmation for a [Community] or [Unverified] server, and, whatever
the tier, when the safety score is in the risk band, MCP Rating has delisted the
package, or a registry name points at a different package than MCP Rating knows
by that name.

### A minimum score

`MCP_GATEWAY_MIN_SCORE=60` (or `"minQualityScore": 60` in `config.json`) refuses
to connect anything MCP Rating scores below 60, or hasn't scored — by slug,
registry name, command or URL alike, so a local `node server.js` is refused too.
`confirmed: true` doesn't lift it, since an agent can set that itself; only the
setting does. It needs MCP Rating among the registries. A value that isn't a
whole number from 0 to 100 refuses everything until it is fixed, rather than
quietly meaning "no rule".

## Registries

By default the gateway searches MCP Rating. It can search any registry that
speaks the [official MCP Registry API](https://registry.modelcontextprotocol.io/docs)
(v0.1) instead, or as well: the official registry, a company's own registry, or
MCP Rating's mirror of it.

```json
{
  "mcpServers": {
    "gateway": {
      "command": "npx",
      "args": ["-y", "@mcp-rating/gateway"],
      "env": {
        "MCP_GATEWAY_REGISTRIES": "https://mcprating.io/api/v1,https://registry.acme.internal"
      }
    }
  }
}
```

- **The list replaces the default.** Leave MCP Rating out and the gateway never
  contacts it for discovery.
- **Each entry is a URL.** One ending in `/api/v1` is taken as MCP Rating's own
  API, and anything else as the MCP Registry API. To say which explicitly, write
  `mcprating=URL` or `mcp-registry=URL`.
- **Searches go to every registry and are merged.** A server two registries both
  list appears once, as the first-listed registry has it. A search waits up to
  15 seconds; a registry that hasn't answered by then is named in the results,
  and the rest are shown.
- **Connecting by name.** A server from an MCP Registry API registry connects by
  its registry name, `mcp_connect({slug: "io.github.owner/server"})`. That works
  in any later session too.
- **Scores come from MCP Rating only.** Quality scores, safety flags and start
  tests are MCP Rating's. When MCP Rating is one of your registries, a server
  found in another one gets MCP Rating's record of the **same package** — the
  same npm or PyPI package, Docker image or hosted endpoint — in one request per
  search. It is matched by package, never by name: any registry can give any
  package a well-known name. Otherwise the server shows as *unrated* and
  [Unverified], so connecting it asks for confirmation. Numbers another
  registry puts in its own entries (`_meta`) are not read: anyone can write them.
- **Warnings that stop a connect.** If MCP Rating knows a server's registry name
  as a different package, or has delisted the package, `mcp_discover` says so,
  lists it last, and `mcp_connect` asks for confirmation whatever its trust tier.
- **The partner key goes to MCP Rating only**, never to another registry.

The official registry's search matches server names only and was slow when this
was written (7–40 s per search on 2026-10-14). The gateway asks it for the
query's longest word and ranks what comes back by how many of your words match.

## 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_REGISTRIES` | Comma-separated registries to search instead (see [Registries](#registries)) | MCP Rating alone |
| `MCP_GATEWAY_MIN_SCORE` | Refuse anything MCP Rating scores below this, or hasn't scored (see [A minimum score](#a-minimum-score)) | no rule |
| `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 so that what a server can see doesn't depend on how your
client happens to start it. 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 the MCP SDK's default allowlist (`HOME`, `LOGNAME`,
`PATH`, `SHELL`, `TERM`, `USER` on macOS and Linux; `PATH`, `USERPROFILE`,
`APPDATA`, `TEMP` and a few more on Windows), 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.

**L1 does not restrict files or the network.** The server runs as your user: it
can read anything you can, including `~/.ssh`, `~/.aws/credentials` and `.env`
files, and it can connect to any host. A manifest can *declare* network and
filesystem limits, but outside a container nothing enforces them, and the
connect summary says "not restricted" rather than listing them.

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

With `MCP_GATEWAY_CONTAINER_ISOLATION=true`, community and unknown servers run
under `docker`/`podman` in an ephemeral container. You can also opt one server
in with `mcp_sandbox({action: "set", slug: "…", enforcement: "l2-container"})`.
Inside, the server gets a read-only root, a scratch `/tmp`, and only the paths
its manifest declares mounted from the host. `network: "none"` gives the
container no network at all. Without Docker or Podman, the gateway falls back to
L1 and logs that it did.

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

Allowlists apply **only under L2.** `network: "allowlist"` starts a forward
proxy and points the container at it via `HTTP_PROXY`/`HTTPS_PROXY`. The proxy
accepts only tunnels that carry a random credential generated for that
connection, which the container receives in those variables. With Docker Desktop
it listens on loopback. With Docker on Linux it has to listen on all interfaces,
because the container reaches it over the bridge, and the credential is what
keeps other machines from using it.

**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 an allowlist as a guard rail against honest
code, not a containment boundary against hostile code. For that, use
`network: "none"`.

### Giving a server an API key

Put the key in the gateway's `env` in your client config, not in the chat:

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

A server receives it only if its registry entry declares that variable. For one
that doesn't, allowlist the **name**, never the value:
`mcp_sandbox({action: "set", slug: "…", envAllow: ["GITHUB_TOKEN"]})`.

`mcp_connect` also accepts `env: { NAME: "value" }`. That works, but the model has
to write the secret into a tool call, which puts it in your chat transcript and
your model provider's logs.

### When a server asks the model for personal data

A hosted server can ask for an email, a phone number or a card number in an
ordinary tool result, and the model is what answers. During our own test runs, a
local 31B was asked for an email "to record your free quota" and made one up.
No sandbox can see that: it's a request in the content channel.

Since 0.2.6 the gateway checks each tool result for a personal-data term next to
a verb of handing it over, in English and Chinese, within its first 1,500
characters. On a match it appends a warning the model reads with the result:
ask the user, and never make up a value. It also records
`personal_data_requested` in the audit trail (`mcp_audit`). It's a heuristic,
and it only adds: the server's reply is never changed or blocked.

### A missing runtime is an error, not a substitution

If a server's launcher (`uvx`, `docker`, `python`, …) isn't installed, the connect
fails with a message naming what to install. Before 0.2.4, a missing launcher was
rewritten to `npx -y <name>`, which ran whatever npm package shared its name. On a
machine without Docker, that was the unrelated npm package `docker`.

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 configured registries — MCP Rating unless you
set `MCP_GATEWAY_REGISTRIES` — for `mcp_discover`, `mcp_connect` and
`mcp_recommend`. That is the lookup you asked for, not background reporting, and
each registry you list sees the searches.
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           # unit tests (env scoping, egress proxy, reconnect, mcp_call_tool)
```

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