protect-mcp

protect-mcp

为 AI Agent 工具调用实施本地策略管控并生成签名决策回执。

开发者页面 · 快速开始 · Agent 设置 · 策略包 · 示例记录 · 集成与贡献 · 文档 · 参与贡献

将网关放在 MCP 客户端与其工具服务之间，或在编码 Agent 中使用其钩子。检查 Cedar 策略，启用强制执行，并保留签名决策记录。本地评估和验证无需 ScopeBlind 账户，也不会发送决策遥测数据。

• 在工具边界实施管控。 在 fail-closed 模式下，Cedar 会在缺少策略、引擎出错或评估出错时拒绝请求。MCP 包装器默认处于影子模式；准备好拦截时，使用 --enforce。
• 检查签名内容。 Ed25519 回执包含决策和策略摘要。@veritasacta/verify 会根据你信任的公钥检查这些字节。
• 从现有工具开始。 使用 MCP stdio、HTTP 网关或编码 Agent 钩子。可选的托管协作有独立的权限和数据流。

网关只覆盖经由它路由的调用。它不是操作系统沙箱，签名回执也不能证明某项操作已经执行，或没有操作被遗漏。安全策略介绍了边界和报告流程。

查看结果

一次真实的本地运行：评估两个拟议调用，为决策签名，验证回执，然后修改一个已签名的决策并再次检查。

观看 14 秒演示

文字演示与复现步骤 · 捕获的结果

不使用 Agent 试用

在新目录中使用 Node.js 22 和 npm。安装固定版本的网关和验证器：

mkdir protect-mcp-demo
cd protect-mcp-demo
npm init -y
npm install --save-exact [email protected] @veritasacta/[email protected]

此示例会评估两个拟议调用并为决策签名。它不会执行任何工具，也不会运行 git push。安装完成后的所有操作都在本地进行。

# Create a starter policy and a private signing key.
npx --no-install protect-mcp init --starter

# A normal read is allowed; a force-push to main is denied (exit 2).
npx --no-install protect-mcp evaluate --policy ./protect.cedar --tool Read --input '{"path":"README.md"}'
npx --no-install protect-mcp evaluate --policy ./protect.cedar --tool Bash --input '{"command":"git push --force origin main"}' || test "$?" -eq 2

# Evaluate again at signing time and record both decisions, in order.
npx --no-install protect-mcp sign --cedar builtin:starter --tool Read --input '{"path":"README.md"}' --key ./protect-mcp.key --receipts ./receipts
npx --no-install protect-mcp sign --cedar builtin:starter --tool Bash --input '{"command":"git push --force origin main"}' --key ./protect-mcp.key --receipts ./receipts

# Take only the public key from the key you generated, not from the receipt.
PROTECT_MCP_PUBLIC_KEY=$(node -p 'JSON.parse(require("fs").readFileSync("protect-mcp.key", "utf8")).publicKey')
npx --no-install verify --replay-chain ./receipts/receipts.jsonl --key "$PROTECT_MCP_PUBLIC_KEY" --json

# Change the signed deny to allow. The original receipt log stays intact.
node -e 'const fs=require("fs");const r=JSON.parse(fs.readFileSync("receipts/receipts.jsonl","utf8").trim().split("\n")[1]);r.payload.decision="allow";fs.writeFileSync("tampered.json",JSON.stringify(r))'
npx --no-install verify tampered.json --key "$PROTECT_MCP_PUBLIC_KEY" --json || test "$?" -eq 1

预期结果：先是 allow，然后是 deny；两个原始回执签名及其链接均通过验证；修改后的回执会报告 invalid_signature。请妥善保管 protect-mcp.key。要验证他人的记录，请通过独立可信渠道获取其预期公钥。

验证器的退出代码为 0：有效、1：无效、2：未检查/出错。验证结果无效不一定意味着遭到篡改：预期公钥错误也会导致验证失败。链重放会检查提供的链接，但无法证明你已收到完整历史记录。

CI 会使用打包后的候选版本和固定的已发布验证器运行此完整示例。请参阅验证与发布。

连接你的 Agent

选择与宿主和所需覆盖范围相匹配的集成方式。 安装指导技能不会启用强制执行。doctor 会检查本地配置；请通过实际执行一次允许的调用和一次被阻止的调用，确认所选路径。

对于 Claude Code 插件，请先准备并启动本地 gate，然后在项目中安装（Claude Code 2.1.295 或更高版本）：

claude plugin install protect-mcp --marketplace ScopeBlind/scopeblind-gateway --scope project

gate 不可用时，插件会阻止路由的工具调用。请选择插件或独立项目钩子，避免同一次调用被记录两次。

用例	从这里开始
包装现有 MCP 服务	MCP 设置和从影子模式到强制执行的工作流
Claude Code 强制执行插件	插件设置和本地 gate
Claude Code 项目钩子	钩子设置
Cursor 项目预览版	显式设置、工具映射和宿主检查
ChatGPT / Codex 助手预览版	设置指南和无害的验证演示，不含钩子
现有的 Claude 目录指导插件	已发布的插件源码，与强制执行分开
将策略评估器作为 MCP 工具调用	作为 MCP 服务运行的 gate
托管 HTTP 网关	HTTP 部署说明

宿主兼容性和发布状态区分了适配器测试与真实宿主验证。Cursor 和助手软件包是预览版，并未列入公开目录。独立钩子格式修复已在 0.32.4 中发布；其变更日志列出了每种格式的变更内容。仅设置格式标志，并不能证明 Codex、Gemini 或 Hermes 集成可正常工作。

对于现有 MCP 服务，请在与上方示例不同的目录中初始化其配置，然后使用服务命令运行包装器：

npx --yes [email protected] init
npx --yes [email protected] --policy ./protect-mcp.json -- node your-mcp-server.js

这会以影子模式启动。请先检查已观察到的调用和策略，再添加 --enforce。wrap 会输出客户端配置并退出；它不是启动命令。完整设置说明。

入门 shell 规则会检查命令文本。这些规则可提供有用的防护，但可能遗漏其他命令写法，也可能匹配无害的引号文本。依赖这些规则之前，请先阅读入门策略的覆盖范围和局限。

集成与贡献

项目	关联方式
Microsoft AI Agents for Beginners	教育资源贡献。 protect-mcp 的维护者编写了第 18 课，介绍如何签名、验证和串联 Agent 回执。
Cedar for Agents	上游贡献。 贡献了 WASM 绑定，以便 JavaScript 和 TypeScript 使用 Cedar 的 Rust MCP 架构生成器。
wshobson/agents	下游集成。 提供 protect-mcp 插件，包含 Claude Code 策略和回执钩子。
TRACE	互操作性检查。 发布 Acta 决策回执测试数据；我们的验证器会根据固定快照报告验证结果。

来源、版本和检查覆盖范围。

从 0.31 升级

0.32.0 关闭了几种绕过门控的方式。其中一些会改变启动方式：

• --http 监听 127.0.0.1，除 GET /health 外的每个请求都需要 Authorization: Bearer <token>。为网关以及调用它的客户端或入口设置相同的 PROTECT_MCP_HTTP_TOKEN（至少 32 个字符）。只有在确实需要将端口暴露给本机以外时， 才使用 --host。
• 配置了签名但密钥缺失或无法读取时，--enforce 会拒绝启动；对于获准但无法签署其回执的调用，也会拒绝执行。
• 使用 --cedar 和 --policy 时，两者都会生效：调用必须获得 Cedar 许可，并通过该文件的 block、require_approval、速率限制和 min_tier 检查。签名和凭据也由该文件提供。
• 控制面板只接受来自其自身页面的更改，该页面带有每次启动时生成的令牌。
• 签名密钥以 0600 权限写入 0700 权限的文件夹。对于早期版本生成的密钥，请运行 chmod 600 keys/gateway.json；完成前，网关会发出警告。
• POST /approve 上的一次性批准会指定确切操作：网关打印的 Request ID，以及 tool:payload_hash。批准 nonce 只会显示在网关的 stderr 中。

每项更改详见更新日志。

文档

• 本地网关指南：策略、钩子、控制面板、凭据和回执兼容性。
• 主机兼容性：强制执行与指导、支持的路由、测试范围和发布状态。
• 回执与披露指南：本地记录、选择性披露和可选的托管摘要锚定。
• 命令参考。
• 可复现的可视化演示：捕获的结果和渲染脚本。
• 集成与贡献：源代码链接、版本以及已发布互操作性检查的范围。
• 托管协调：独立的人为审批、发票沙盒和仓库审查工作流。
• 发布验证与来源证明。
• 按版本查看更改。

参与贡献

可从范围明确的待帮助任务开始： 一次真实主机捕获、 另一种干净的软件包运行环境，或 一份经过测试的策略示例。

欢迎提交错误报告、最小复现示例、文档修正和兼容性测试。有关设置和检查，请参阅 CONTRIBUTING.md；有关维护工作，请参阅 GOVERNANCE.md。请通过 SECURITY.md 私下报告漏洞， 不要在公开议题中报告。

共享一致性测试语料库 记录了不同回执生成方的兼容性结果。测试语料库通过，只能作为范围有限的互操作性证据， 并不代表获得了安全认证。

采用 MIT 许可证；详见 LICENSE 和现有的专利声明。 由 ScopeBlind 的 Tom Farley 维护。回执格式： Acta 独立 Internet-Draft。