@mcp-rating/gateway

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.

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.

{ "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.

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:

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:

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 —

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

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

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

Claude Code

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

Windsurf

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

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

Any other MCP client

{ "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:

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:

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

Environment Variables

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.

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:

{
  "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 SIGKILLed, 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

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

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