---

name: protect-mcp-governance description: "MCP 工具调用的代理治理技能——Cedar 策略编写、影子模式到强制执行的渐进部署，以及 Ed25519 收据验证。" risk: safe source: community source_repo: scopeblind/scopeblind-gateway source_type: official date_added: "2026-04-05"

使用 protect-mcp 的 MCP 代理治理

概述

使用 Cedar 策略和 Ed25519 签名收据治理 AI 代理工具调用的指南。此技能教授如何为 MCP 服务器编写访问控制策略、在影子模式下运行以进行观察，以及验证加密审计跟踪。

何时使用此技能

• 需要控制代理可以调用哪些 MCP 工具以及在什么条件下调用时
• 需要代理工具执行的防篡改审计跟踪时
• 渐进式部署治理策略时（先影子模式，再强制执行）
• 为 MCP 工具访问控制编写 Cedar 策略时
• 验证收据或审计包未被篡改时

何时不使用此技能

• 需要通用应用安全审计时（使用 @security-auditor）
• 需要扫描代码漏洞时（使用 @security-audit）
• 需要不涉及代理特定治理的合规框架指导时

工作原理

protect-mcp 拦截 MCP 工具调用，根据 Cedar 策略（与 AWS Verified Permissions 使用的相同策略引擎）进行评估，并将每个决策签名为 Ed25519 收据。收据是加密证明，证明特定策略在特定时间对特定工具调用进行了评估。

Agent → protect-mcp → Cedar 策略评估 → MCP Server
                ↓
        Ed25519 签名收据

三种运行模式：

1. 影子模式（默认）— 记录决策但不阻止。用于在强制执行前观察策略效果。
2. 强制模式 — 阻止违反策略的工具调用。在影子模式验证后使用。
3. 钩子模式 — 与 Claude Code 钩子集成，实现工具调用前/后治理。

核心概念

Cedar 策略

Cedar 是为授权设计的策略语言。策略通过 WASM 在本地评估——无需网络调用。

// Allow read-only file operations
permit(
  principal,
  action == Action::"call_tool",
  resource
) when {
  resource.tool_name in ["read_file", "list_directory", "search_files"]
};

// Deny destructive operations
forbid(
  principal,
  action == Action::"call_tool",
  resource
) when {
  resource.tool_name in ["execute_command", "delete_file", "write_file"]
  && resource has args
  && resource.args.contains("rm -rf")
};

签名收据

每个策略决策产生一个签名收据：

{
  "payload": {
    "type": "protectmcp:decision",
    "tool_name": "read_file",
    "decision": "allow",
    "policy_digest": "sha256:9d0fd4c9e72c1d5d",
    "issued_at": "2026-04-05T14:32:04.102Z",
    "issuer_id": "sb:issuer:de073ae64e43"
  },
  "signature": {
    "alg": "EdDSA",
    "kid": "sb:issuer:de073ae64e43",
    "sig": "2a3b5022..."
  }
}

收据格式遵循 IETF Internet-Draft draft-farley-acta-signed-receipts。

分步指南

1. 为项目初始化治理

# Install and initialize hooks (Claude Code integration)
npx protect-mcp init-hooks

# Or run as a standalone MCP gateway
npx protect-mcp serve

这会在项目根目录创建 protect-mcp.config.json 和一个入门 Cedar 策略。

2. 编写你的第一个策略

在项目中创建 policy.cedar：

// Start permissive — allow everything in shadow mode
permit(
  principal,
  action == Action::"call_tool",
  resource
);

3. 在影子模式下运行（先观察）

# Shadow mode is the default — logs decisions without blocking
npx protect-mcp --policy policy.cedar -- node your-mcp-server.js

在编写限制性策略之前，审查影子日志以了解代理的行为。

4. 收紧并强制执行

了解工具调用模式后，编写具体策略：

// Allow file reads, deny writes outside src/
permit(
  principal,
  action == Action::"call_tool",
  resource
) when {
  resource.tool_name == "read_file"
};

permit(
  principal,
  action == Action::"call_tool",
  resource
) when {
  resource.tool_name == "write_file"
  && resource has args
  && resource.args.path like "src/*"
};

// Deny everything else
forbid(
  principal,
  action == Action::"call_tool",
  resource
);

切换到强制模式：

npx protect-mcp --policy policy.cedar --enforce -- node your-mcp-server.js

5. 验证收据

# Verify a single receipt
npx @veritasacta/verify receipt.json --key <public-key-hex>

# Verify an audit bundle (multiple receipts + keys)
npx @veritasacta/verify bundle.json --bundle

# Self-test the verifier (proves it works offline)
npx @veritasacta/verify --self-test