gateway

@mcp-rating/gateway

运行 MCP 服务，无需向它们提供你环境中的 API 密钥。

你添加的服务能否读取你的环境变量（AWS_SECRET_ACCESS_KEY、 OPENAI_API_KEY、DATABASE_URL），取决于客户端如何启动它。官方 MCP SDK 默认只传递一份简短的允许列表：HOME、PATH、USER 等少数变量。有些客户端或脚本会传递整个环境，通常只是为了转发服务所需的某个令牌，却因此交出了所有信息。我们尚未测量哪些热门客户端会采取哪种做法，因此不点名。网关不会把这件事交给客户端决定：它会使用构造好的环境启动每个服务，即 SDK 的简短允许列表（PATH、HOME、USER 等少数变量），再加上你或服务清单中指定的变量。你的环境中的其他内容都无法被读取。

文件则是另一回事。 默认情况下，服务仍会以你的身份运行，因此能读取你可以读取的内容——~/.ssh、~/.aws/credentials、项目的 .env。只有容器隔离（需主动启用，并需要 Docker）才能阻止这一点。请参阅各级别的保护范围。

	使用整个环境启动	通过网关运行
服务可见的环境	客户端拥有的所有内容	简短的允许列表（PATH、HOME、USER 等少数变量），以及你指定的变量
环境变量中的凭据	全部	你未指定的凭据，一个也没有
凭据文件（~/.ssh、~/.aws、.env）	可读取	仍可读取，除非启用了容器隔离

只需约十秒即可自行复现：node demo/run-demo.mjs 会植入两个假凭据，并以两种方式运行服务。它会完整打印植入的值；对于在环境中发现的任何真实变量，只打印变量名，绝不打印变量值。GIF 由 node demo/render-gif.mjs 在干净的合成环境中生成，因此不会显示任何真实机器上的信息。

它也是一个元服务：只需在配置中添加一个入口，就能获得完整的注册表；服务会按需连接，而非预先加载。

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

为什么它占用的上下文更少

你静态配置的每个 MCP 服务，都会在每一轮中注入其完整的工具架构，无论你是否使用它。网关以固定开销提供 13 个元工具，并且只会在你连接到某个服务后加载该服务的工具。

	测量值
中位数 MCP 服务	2,587 个 token
静态配置 10 个服务	约 25,900 个 token，每一轮都会占用
网关，精简版	2,644 个 token

配置 10 个服务时，持续开销约减少 10 倍，并且随着添加的服务增多，差距还会扩大。单个中位数服务的开销，已经与整个网关相当。

但常驻开销不等于实际成本——盈亏平衡点在这里

这个 10× 指的是窗口中常驻的内容。它不代表一次对话的成本，因为网关还会增加轮次：使用服务器前必须先发现并连接服务器；每一轮都会重新发送完整的对话记录；而 mcp_discover 的输出之后也会一直留在对话记录中。

使用 vLLM 上的 gemma-4-31B 进行端到端测量，采用服务器自己的分词器，而非估算值：

	tokens	轮次
网关，冷启动——发现、连接，然后调用工具	17,904	5
调用同一工具，服务器已配置	6,605	2

只有一个服务器时，网关的成本是直接配置它的 2.7×。 只有当服务器足够多，携带所有服务器的架构定义所需的开销超过初始化成本时，才能节省开销。已配置 N 个服务器，实际使用 1 个，完成十轮工作后：

服务器数	静态配置	网关
1	25,870	70,524	静态配置胜出 2.7×
2	51,740	70,524	静态配置胜出 1.4×
4	103,480	70,524	网关胜出 1.5×
10	258,700	70,524	网关胜出 3.7×
20	517,400	70,524	网关胜出 7.3×

盈亏平衡点是 3 到 5 个服务器。 少于这个数量时，手动编写配置确实更省，应该采用这种方式。超过这个数量后，网关更胜一筹，而且随着服务器增加，优势也会持续扩大——但在 10 个服务器时，按总 token 数计算的真实优势约为 3×，而不是只计算常驻开销得出的 10×。

如实说明测量方法： 从本项目连接并检查过的 91 个服务器的工具架构定义中测量，这些服务器选自注册表中下载量最高的 300 个；对每个工具的 {name, description, inputSchema} 求和，即客户端通过 tools/list 实际收到的载荷，并按 chars / 4 估算。这只是估算值，并非分词器的结果。

这里用的是中位数，而非平均值，原因就在于数据分布。 平均值为 9,965 个 token，但被长尾拉高：91 个服务器中有 19 个超过 10,000 个 token；开销最高的是一个提供 608 个工具的 Spotify 服务器，单独就需要 135,666 个 token，约占 200k 上下文窗口的 68%。引用平均值会让本项目的数字显得更有利，因为其中计入了几乎没人安装的服务器。

节省确实存在，正是因为大多数已配置的服务器在大多数对话中都不会用到——但在假设这对你也适用之前，请先参考上面的盈亏平衡点。

使用 chars / 4 的估算值与三种真实分词器进行了比对，结果分别为真实 token 数的 0.88×、0.98× 和 1.01×，因此从不会低估。

复现两项测量：运行 node demo/shorts/short2-context.mjs --refresh 获取架构定义数据集，运行 demo/ollama-probe.mjs 查看端到端成本——

# 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

工作原理

┌────────────────────┐       ┌──────────────┐       ┌──────────────────┐
│  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 │
                             └──────────────┘

无需在客户端中手动配置每个 MCP 服务器，网关会：

1. 发现 MCP-Rating 注册表中的服务器，并优先列出可立即启动的服务器（见下文）
2. 按需连接到这些服务器：将本地服务器作为子进程启动，并连接托管服务器至注册表列出的端点
3. 通过带命名空间的名称（servername__toolname）代理它们的工具
4. 在添加或移除工具时通知客户端

快速开始

使用 Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

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

然后向 Claude 提问：

• “搜索可与数据库配合使用的 MCP 服务器”（使用 mcp_discover）
• “连接到 sqlite 服务器”（使用 mcp_connect）
• “查询我的数据库”（直接调用被代理的工具）

Cursor

~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "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，格式与 Cursor 相同：

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

Kiro

添加到 Kiro （Kiro 会在安装前征求确认），或者使用 ~/.kiro/settings/mcp.json（工作区中使用 .kiro/settings/mcp.json），格式与 Cursor 相同：

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

Kiro 仅在你登录后运行 MCP 服务；如果其 MCP Servers 面板显示 Enable MCP，请先点击它。

Kiro 会忽略 tools/list_changed。它只会在连接时读取一次网关的工具列表，因此之后连接的服务所提供的工具不会直接提供给 Agent。请让 Agent 通过 mcp_call_tool 调用这些工具，并使用 mcp_connect 打印的完整 slug__tool 名称。在 Kiro 1.4.26 上使用 demo/client-probe.mjs 测得。

其他 MCP 客户端

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

编辑配置后请重启客户端——大多数客户端只会在启动时读取配置。

mcp_discover 会优先显示什么

Agent 只能使用网关能够启动的服务，因此结果会按以下顺序排列，每组内部仍按相关性排序：

1. 已验证：注册表自带的测试程序成功启动该服务，并列出了其工具 （✓ Started in our test）。
2. 就绪，未测试：可在此处安装，或无需请求头的托管端点，且其声明的密钥均已设置。
3. 需要设置：某个声明的密钥尚未设置、其启动器（uvx、docker）尚未安装，或托管端点需要网关目前无法发送的请求头。
4. 测试失败：注册表尝试启动时未能启动，且未提供凭据 （✗ Didn't start in our test）。
5. 无法按 slug 启动：没有安装命令，也没有记录端点。

“已验证”表示服务成功启动并列出了工具，并不意味着每个工具都能在没有密钥的情况下运行。测试程序不会提供任何密钥。大多数索引条目从未经过测试；这既不能说明它们好，也不能说明它们不好。

元工具

网关提供 13 个内置工具：

工具	说明
mcp_discover	搜索 MCP-Rating 注册表；网关当前能够启动的服务会优先显示
mcp_connect	连接到服务并提供其工具
mcp_disconnect	断开服务连接并移除其工具
mcp_list_active	列出已连接的服务及其工具
mcp_server_info	查看服务的详细信息，信息来自注册表或实时连接
mcp_call_tool	调用已连接服务上的工具
mcp_gateway_health	诊断信息：版本、运行时间、连接和注册表状态
mcp_sandbox	查看或自定义服务的沙箱清单（环境变量/网络/文件系统）
mcp_audit	安全审计记录——沙箱服务实际执行的操作
mcp_profiles	命名连接配置（工作、个人，……）
mcp_groups	原子化地连接/断开一组服务
mcp_usage	已连接服务的调用次数、延迟和错误率
mcp_recommend	根据使用情况推荐服务

信任等级

每个已连接的服务都会根据其 MCP-Rating 质量评分标记信任等级：

• [Verified] — 高质量且经过官方验证
• [Trusted] — 质量良好，有代码仓库，且提供安装命令或远程端点
• [Community] — 已列入注册表，质量达到基本标准
• [Unverified] — MCP Rating 不认识的软件包，来自任何注册表，或通过命令启动的软件包

如果安全评分处于风险区间，信任等级会受到限制，与网站上的规则相同：低于 50 时，服务最高为 [Community]；低于 30 时为 [Unverified]。

mcp_connect 会显示什么，以及何时会先询问

在启动任何内容之前，mcp_connect 会查询 MCP Rating 中有关待运行程序包的信息——这些信息来自注册表条目；如果指定了 command 或 url，则来自程序包本身（npx pkg、uvx pkg、docker run image、端点）。通过命令启动的已知程序包会按其自身进行评估，而不会被标记为 [Unverified]。确认时会显示这些信息，连接后也会再次显示：

• 评分和信任等级，以及服务页面；
• 安全评分和每项标记及其原因；
• MCP Rating 自身的启动测试结果：已启动、未启动、需要凭据或未测试；
• 最近一次发布和最近一次代码推送，以及每个日期的来源。

对于 [Community] 或 [Unverified] 服务，它会请求确认；无论信任等级如何，若安全评分处于风险区间、MCP Rating 已将程序包下架，或注册表名称指向的程序包与 MCP Rating 以该名称记录的程序包不同，也会请求确认。

最低评分

MCP_GATEWAY_MIN_SCORE=60（或 config.json 中的 "minQualityScore": 60）会拒绝连接任何 MCP Rating 评分低于 60 或尚未评分的对象，不论使用 slug、注册表名称、命令还是 URL，因此本地的 node server.js 也会被拒绝。confirmed: true 不会解除此限制，因为 Agent 可以自行设置该值；只有配置项可以解除限制。配置中必须包含 MCP Rating。若值不是 0 到 100 之间的整数，就会拒绝所有连接，直到修正为止，而不会静默地将其视为“无规则”。

注册表

默认情况下，网关会搜索 MCP Rating。也可以改为或同时搜索任何支持官方 MCP Registry API（v0.1）的注册表：官方注册表、公司自己的注册表，或 MCP Rating 对它的镜像。

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

• 列表会替换默认设置。 如果列表中不包含 MCP Rating，网关就不会联系它进行发现。
• 每个条目都是一个 URL。 以 /api/v1 结尾的 URL 会被视为 MCP Rating 自身的 API，其他 URL 则会被视为 MCP Registry API。若要明确指定类型，请写成 mcprating=URL 或 mcp-registry=URL。
• 搜索会发送到每个注册表，并合并结果。 如果两个注册表都列出了同一个服务，它只会出现一次，并采用列表中靠前的注册表所记录的信息。搜索最多等待 15 秒；超时前尚未响应的注册表会在结果中注明，其余结果仍会显示。
• 按名称连接。 来自 MCP Registry API 注册表的服务可通过其注册表名称连接：mcp_connect({slug: "io.github.owner/server"})。之后的任何会话也都可以这样连接。
• 评分仅来自 MCP Rating。 质量评分、安全标记和启动测试均来自 MCP Rating。当 MCP Rating 是你的注册表之一时，在另一个注册表中找到的服务会通过一次搜索请求，获取 MCP Rating 中有关同一个程序包的记录——同一个 npm 或 PyPI 程序包、Docker 镜像或托管端点。匹配依据是程序包，而不是名称：任何注册表都可以给任何程序包指定一个广为人知的名称。否则，该服务会显示为未评分和 [Unverified]，因此连接时会请求确认。不会读取其他注册表在自身条目（_meta）中填写的数字：任何人都可以填写这些数字。
• 会阻止连接的警告。 如果 MCP Rating 记录的服务注册表名称对应的是另一个程序包，或已将该程序包下架，mcp_discover 会说明这一点并将其列在最后，而 mcp_connect 无论其信任等级如何都会请求确认。
• 合作伙伴密钥只会发送给 MCP Rating，绝不会发送给其他注册表。

官方注册表的搜索只匹配服务名称，而且在撰写本文时速度较慢（截至 2026-10-14，每次搜索需 7–40 秒）。网关会使用查询中最长的单词向它发起搜索，并根据返回结果与查询中匹配的词数进行排序。

配置

网关会从 ~/.mcp-gateway/config.json 读取配置：

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

环境变量

变量	描述	默认值
MCP_GATEWAY_REGISTRY_URL	MCP-Rating API 基础 URL	https://mcprating.io/api/v1
MCP_GATEWAY_REGISTRIES	改为搜索以逗号分隔的注册表（参见注册表）	仅 MCP Rating
MCP_GATEWAY_MIN_SCORE	拒绝 MCP Rating 评分低于此值或尚未评分的项目（参见最低分数）	无规则
MCP_GATEWAY_TIMEOUT	代理超时（毫秒）	30000
MCP_GATEWAY_MAX_CONNECTIONS	最大同时连接数	10
MCP_GATEWAY_LOG_LEVEL	日志级别（debug/info/warn/error）	info
MCP_GATEWAY_CONTAINER_ISOLATION	强制开启/关闭 L2 容器隔离	由清单决定
MCP_GATEWAY_AUDIT_LOG	取证审计日志的路径	已禁用
MCP_GATEWAY_PARTNER_KEY	合作伙伴归因密钥 — 启用广告遥测	未设置
MCP_GATEWAY_AD_TRACKING	设置为 false 可彻底禁用广告遥测	未设置
MCP_GATEWAY_HTTP_TOKEN	HTTP 守护进程模式的 Bearer 令牌	未设置

安全模型

此网关旨在确保服务器能看到的内容不取决于客户端启动它的方式。两层防护共同发挥作用，了解每层的作用与局限很重要。

L1 — 环境变量范围控制（始终开启，适用于 stdio 服务器）

下游服务器会收到 MCP SDK 的默认允许列表（macOS 和 Linux 上为 HOME、LOGNAME、 PATH、SHELL、TERM、USER；Windows 上为 PATH、USERPROFILE、 APPDATA、TEMP 以及其他少数变量），以及清单允许列表中的变量名称，或你在连接时传入的变量名称。父环境中的其他所有内容（AWS_*、OPENAI_API_KEY、DATABASE_URL）都会被隐藏。导出的 Shell 函数（BASH_FUNC_*）会被丢弃，而不会转发。

这是真正的强制措施：子进程使用构造好的环境启动，因此没有可以选择退出或绕过的机制。

**L1 不会限制文件或网络访问。**服务器以你的用户身份运行：它可以读取你能读取的任何内容，包括 ~/.ssh、~/.aws/credentials 和 .env 文件，也可以连接到任何主机。清单可以声明网络和文件系统限制，但在容器之外，这些限制不会得到强制执行；连接摘要会显示“未受限制”，而不是列出这些限制。

L2 — 容器隔离（选择启用）

将 MCP_GATEWAY_CONTAINER_ISOLATION=true 后，社区服务器和未知服务器会在临时 docker/podman 容器中运行。你也可以通过 mcp_sandbox({action: "set", slug: "…", enforcement: "l2-container"}) 单独为某个服务器启用此功能。在容器内，服务器会获得只读根目录、临时 /tmp，以及清单声明从主机挂载的路径。设置 network: "none" 后，容器将完全无法访问网络。如果没有 Docker 或 Podman，网关会回退到 L1，并记录此情况。

网络允许列表：依赖之前请先阅读

允许列表仅在 L2 下生效。network: "allowlist" 会启动一个转发代理，并通过 HTTP_PROXY/HTTPS_PROXY 将容器指向该代理。代理只接受携带为该连接生成的随机凭据的隧道，而容器会通过这些变量收到凭据。使用 Docker Desktop 时，代理会监听环回地址。使用 Linux 上的 Docker 时，由于容器通过网桥访问代理，因此代理必须监听所有网络接口；凭据可防止其他机器使用该代理。

**这只会过滤遵循代理设置的客户端。**Node 的 fetch/undici、axios 和 Python requests 都会遵循这些变量，涵盖了大多数实际服务器。打开原始 TCP 套接字的程序，或忽略代理环境变量的已编译二进制文件，不会受到过滤。应将允许列表视为针对可信代码的防护措施，而非抵御恶意代码的隔离边界。要实现后者，请使用 network: "none"。

为服务提供 API 密钥

将密钥放在客户端配置中网关的 env 里，而不是放在聊天中：

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

只有在服务的注册表条目声明了该变量时，服务才会收到它。对于未声明该变量的服务，请将变量名称加入允许列表，绝不要加入变量值： mcp_sandbox({action: "set", slug: "…", envAllow: ["GITHUB_TOKEN"]})。

mcp_connect 也接受 env: { NAME: "value" }。这也能用，但模型必须将密钥写入工具调用，这会使密钥出现在聊天记录和模型提供商的日志中。

当服务向模型索取个人数据时

托管服务可以在普通工具结果中索取电子邮件地址、电话号码或卡号，由模型作答。在我们自己的测试运行中，有人要求一款本地 31B 模型提供电子邮件地址，理由是“记录你的免费额度”，结果它编造了一个。沙箱无法察觉这种情况：这是内容通道中的请求。

从 0.2.6 开始，网关会在每个工具结果的前 1,500 个字符中检查是否有表示交出个人数据的词语与动作动词相邻出现，支持英语和中文。匹配时，网关会附加一条模型会随结果读取的警告：询问用户，绝不要编造数据。它还会在审计记录（mcp_audit）中记录 personal_data_requested。这是一种启发式检查，只会追加警告：绝不会更改或拦截服务的回复。

缺少运行时会报错，不会替换

如果服务的启动器（uvx、docker、python 等）未安装，连接会失败，并提示需要安装什么。0.2.4 之前，缺少启动器时会被改写为 npx -y <name>，从而运行任何名称相同的 npm 包。在没有 Docker 的机器上，这运行的竟是无关的 npm 包 docker。

允许列表模式采用默认拒绝：格式错误的模式（例如缺少点号的 *example.com）不会匹配任何内容，而不是匹配所有内容。网关会在启动时警告那些无法实现作者预期的模式，包括 *.com 这类范围过宽的模式。

不涵盖的情况

如果宿主客户端遭到 SIGKILL，网关无法执行关闭流程，已启动的子进程可能会遗留。SIGINT/SIGTERM 会得到处理，并能干净地断开所有连接；按定义，SIGKILL 无法捕获。

遥测

除非主动启用，否则默认关闭。 只有在设置了 MCP_GATEWAY_PARTNER_KEY 时才会创建广告跟踪器——未设置合作伙伴密钥时，不会进行合作伙伴遥测，也不会上报连接或工具调用信息。

如果设置了合作伙伴密钥（即你正在获得归因收入），连接和工具执行事件会发送到 mcprating.io。如需保留密钥但禁用跟踪，请设置 MCP_GATEWAY_AD_TRACKING=false。

此外，网关会调用已配置的注册表——除非设置了 MCP_GATEWAY_REGISTRIES，否则使用 MCP Rating——以处理 mcp_discover、mcp_connect 和 mcp_recommend。这是你请求的查询，不是后台报告；你列出的每个注册表都会看到搜索内容。 使用分析（mcp_usage）是内存中的环形缓冲区，绝不会离开进程。

开发

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)

架构

该网关基于 MCP SDK 构建，并使用：

• StdioServerTransport — 与宿主客户端通信
• StdioClientTransport — 启动并与下游服务通信
• 动态工具注册 — McpServer.registerTool() + sendToolListChanged()
• 工具命名空间 — slug__toolname 模式可防止名称冲突
• 直通 Zod 架构 — 为宿主客户端 UI 保留参数名称，同时让下游服务进行验证

许可证

MIT — 参见 LICENSE。

---

如果这避免了你把密钥交给陌生人的代码，点个 ⭐ 能帮助其他人找到这个项目。