SafeNode MCP Gateway

SafeNode MCP 网关

一个会对每次工具调用执行策略检查的 MCP 代理。Agent 无法绕过它。

npx safenode-mcp-gateway

为什么需要代理

一个提供 evaluate_action 工具的 MCP 服务只是在做样子。模型可以选择不调用它，这意味着它什么也管不了。

这是一个代理。它位于 MCP 客户端（Claude Desktop、Claude Code、Cursor 或任何 MCP 主机）与您已在使用的 MCP 服务之间。tools/list 会直接通过，因此模型看到的工具与之前完全相同。每次 tools/call 都会先由 SafeNode 评估。若请求被拒绝，调用根本不会到达下游服务。

Claude Desktop ──► safenode-mcp-gateway ──► filesystem server
                          │                   github server
                          ▼                   postgres server
                    SafeNode API
                  allow/warn/review/deny

您的 Agent 无需更改任何代码。它不会知道网关的存在。

获取 API 密钥——免费套餐，无需银行卡 · 文档 · Python SDK

---

设置

1. 获取 API 密钥

在 safenode.tech 免费获取。密钥的格式类似 sn_...。

2. 编写配置

safenode-gateway.json——直接从现有 MCP 客户端配置中复制服务：

{
  "failMode": "fail_closed",
  "payloadMode": "redacted",
  "logFile": "./safenode-decisions.jsonl",
  "servers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    }
  ],
  "tools": {
    "read_file": { "failMode": "fail_open" },
    "write_file": { "payloadMode": "metadata_only" }
  }
}

不要将 API 密钥放入此文件。在环境中设置 SAFENODE_API_KEY——它的优先级高于配置文件，因此该文件可以安全地提交。

3. 先查看将要发送的内容，再发送任何内容

SAFENODE_API_KEY=sn_... npx safenode-mcp-gateway --dry-run

打印评估请求将要 POST 的确切 JSON 正文。不会发起网络调用。这是确认哪些数据会离开您设备的最快方式。

4. 将 MCP 客户端指向网关

Claude Desktop——claude_desktop_config.json：

{
  "mcpServers": {
    "safenode": {
      "command": "npx",
      "args": ["-y", "safenode-mcp-gateway", "--config", "/absolute/path/to/safenode-gateway.json"],
      "env": { "SAFENODE_API_KEY": "sn_..." }
    }
  }
}

Claude Code——项目中的 .mcp.json：

{
  "mcpServers": {
    "safenode": {
      "command": "npx",
      "args": ["-y", "safenode-mcp-gateway", "--config", "./safenode-gateway.json"],
      "env": { "SAFENODE_API_KEY": "sn_..." }
    }
  }
}

Cursor——~/.cursor/mcp.json，格式与 Claude Desktop 相同。

用此配置替换现有的服务条目。网关会自行启动这些服务，因此如果在两个地方都列出它们，每个服务都会运行两次。

---

各项决策的作用

决策	行为
allow	转发。下游结果原样返回。
warn	转发，并在前面添加一行 [SafeNode warning]，让模型和用户都能看到警告。
review	**不转发。**返回一条说明需要审批的消息。
deny	**不转发。**返回面向用户的原因以及 trace_id。

拒绝请求会作为 MCP 工具错误返回，而非传输失败，因此模型能看到原因并尝试其他操作，而不是由主机显示一个含糊的崩溃错误。

故障时的行为

当 SafeNode 本身无法访问时，failMode 决定如何处理。

fail_closed （默认）	阻止调用。
fail_open	未经评估就转发。
raise	使网关崩溃。

**网关默认采用 fail_closed，与默认采用 fail_open 的 SafeNode SDK 不同。**这是有意为之。SDK 封装的是开发者自己的代码；在 SafeNode 服务中断期间导致生产环境宕机会让用户永远流失。网关则面向各种它并不了解的 MCP 工具——文件系统写入、Shell 命令、支付等。一旦 SafeNode 无法访问就默默放行所有操作，会让安装网关失去意义。

可针对只读工具放宽策略：

"tools": {
  "read_file":   { "failMode": "fail_open" },
  "list_files":  { "failMode": "fail_open" }
}

降级决策会记录到 stderr，并在决策日志中标记为 "degraded": true，且 traceId 为 null，因此绝不会被计为真实的策略决策。

哪些数据会离开您的设备

对于每次工具调用，网关都会发送：工具名称、下游服务名称、会话 ID、配置中的静态上下文，以及作为载荷的工具参数。

payloadMode 控制参数的处理方式：

full	原样发送。
redacted （默认）	先在客户端进行脱敏。
metadata_only	不发送任何值——仅发送键名和哈希值。

脱敏范围包括电子邮件地址、经 Luhn 算法验证的信用卡号、美国 SSN、服务提供商 API 密钥前缀（sk-、ghp_、xoxb-、AKIA、AIza）、Bearer 令牌以及 PEM 私钥块。值会替换为 [REDACTED:<type>]。

为什么始终会发送脱敏计数

除了脱敏后的载荷，网关还会发送被移除内容的计数：

"safenode_redactions": { "email": 2, "credit_card": 1 }

这至关重要。SafeNode 服务端的 sensitive_data 规则会针对载荷中的值匹配模式。如果网关清除了这些值却不作说明，那么“拒绝任何包含卡号的操作”这一策略就会在不知不觉中开始放行——客户端隐私功能会禁用服务端安全控制。报告计数可以避免这种情况：策略可以根据是否存在卡号采取行动，却始终不会收到卡号本身。

如果你将 sensitive_data 与 patterns 搭配使用，请同时配置 redaction_metadata 规则。

这些计数由客户端自行报告。它们能为诚实的客户端设定最低保障，但无法防范恶意客户端。

无遥测

网关只与两类对象通信：你配置的下游 MCP 服务，以及 SafeNode API。没有分析、没有自动回传数据，也没有 postinstall 脚本。

本地决策日志

设置 logFile，即可记录每项决策的 JSONL 记录，且独立于服务端审计轨迹——这样即使网络中断，你仍能留存 Agent 尝试执行操作的证据：

{"timestamp":"2026-08-08T04:12:09.412Z","server":"filesystem","tool":"write_file","decision":"deny","degraded":false,"traceId":"9f1c…","reasons":["Path is outside the approved workspace."],"forwarded":false,"durationMs":143,"sessionId":"a3f1…"}

配置参考

键	默认值	含义
apiKey	—	优先使用环境变量 SAFENODE_API_KEY
baseUrl	https://safenode.tech	用于预发布环境
failMode	fail_closed	fail_closed | fail_open | raise
payloadMode	redacted	full | redacted | metadata_only
timeoutMs	5000	评估请求的时间预算
logFile	null	JSONL 决策日志路径
prefixTools	false	强制采用 <server>__<tool> 命名
servers[]	required	下游 MCP 服务
tools{}	{}	针对各工具的覆盖设置
context{}	{}	每次评估时附带的静态上下文

failMode、payloadMode 和 context 可以全局设置，也可以按服务或工具设置。优先级以最具体的设置为准。

tools.<name>.bypass: true 会对某个工具完全跳过评估。正如其名称所示——调用会直接转发，不进行任何策略检查。

工具名称冲突

如果两个下游服务导出同名工具，网关会为每个工具添加 <server>__ 前缀，并记录警告。悄悄选择其中一个，会导致一个服务的策略被应用于另一个服务的工具。这不是外观问题，而是安全漏洞。

本工具不是什么

• 不是沙箱。 它决定是否转发调用，但不会隔离下游服务、限制系统调用，也不会限制该服务收到调用后能做什么。
• 不是提示词注入检测器。 它评估的是操作，而不是产生该操作的推理过程。如果 Agent 被诱导去删除某张表，本工具可以阻止删除，但不会告诉你 Agent 受到了操纵。
• 不支持离线使用。 每次工具调用都需要往返 SafeNode API。没有本地策略评估。
• 不能替代对底层服务设置范围限制。 仍应向文件系统服务传入满足需求的最窄根目录。
• 不会消除副作用。 每次评估都会记录在服务端，并计入你的月度配额。

延迟

每次受控工具调用都会额外产生一次与 SafeNode API 的往返，默认时间预算为 5000 ms。 绕过评估的工具不会增加延迟。

目前尚未公布 evaluate 端点的实测 p99，因为尚未在真实负载下进行测量。完成测量后，结果会发布在这里和文档中，而不是估算得出。

Docker

docker build -t safenode-mcp-gateway .

不带参数运行时，会使用捆绑的演示配置启动，并代理随附的 echo 服务，因此无需进行任何设置即可查看代理的工作情况：

docker run -i --rm safenode-mcp-gateway

演示密钥只是占位符，因此 tools/list 会透传，而任何实际工具调用都会被 fail_closed 策略拒绝。实际使用时，请挂载自己的配置并提供密钥：

docker run -i --rm \
  -e SAFENODE_API_KEY=sn_... \
  -v /path/to/safenode-gateway.json:/app/config.json \
  safenode-mcp-gateway --config /app/config.json

必须使用 -i。MCP 通过标准输入输出流传输 JSON-RPC，因此如果未连接标准输入，网关就无法通信。

Agent 技能

SKILL.md 教 Agent 如何为你设置网关、将现有服务迁移到网关后方，以及在调用被拦截或暂缓以供审核时如何处理。将它复制到 Agent 技能目录下的文件夹中（对于 Claude Code，该目录为 ~/.claude/skills/safenode-mcp-gateway/）。策略编写配套指南位于 skill/safenode-policies/。

要求

Node 18+。一个运行时依赖：@modelcontextprotocol/sdk。

贡献

请参阅 CONTRIBUTING.md。有关策略执行漏洞的错误报告——即任何本应被拦截却到达下游服务的情况——是最有价值的反馈。

安全

请参阅 SECURITY.md。请不要公开提交漏洞相关问题。

许可证

MIT。请参阅 LICENSE。