Skip to content

wshobson/agents / plugins/protect-mcp/skills/protect-mcp-setup

protect-mcp-setup

Unverified

Configure Cedar policy enforcement and Ed25519 signed receipts for Claude Code tool calls. Use when setting up projects that need cryptographic audit trails, policy-gated tool execution, or compliance-ready evidence of agent actions.

protect-mcp — Policy Enforcement + Signed Receipts

Cryptographic governance for every Claude Code tool call. Each invocation is evaluated against a Cedar policy and produces an Ed25519-signed receipt that anyone can verify offline.

Overview

Claude Code runs powerful tools: Bash, Edit, Write, WebFetch. By default there is no audit trail, no policy enforcement, and no way to prove what was decided after the fact. protect-mcp closes all three gaps:

  • Cedar policies (AWS's open authorization engine) evaluate every tool call before execution. Cedar deny is authoritative.
  • Ed25519 receipts record the name of each tool that ran, signed with your key.
  • Offline verification via npx @veritasacta/verify. No server, no account, no trust in the operator.

Problem

AI agents make decisions that affect money, safety, and rights. The Claude Code session log records what happened, but the log is:

  • Mutable — anyone with access can edit it
  • Unsigned — there is no way to prove integrity
  • Operator-bound — verification requires trusting whoever holds the log

For compliance contexts (finance, healthcare, regulated research), this is not sufficient. You need tamper-evident evidence that can be verified by third parties without trusting you.

Solution

Add protect-mcp to your Claude Code project:

# 1. Install the plugin (adds hooks + skill to your project)
claude plugin install wshobson/agents/protect-mcp

# 2. Create ./protect.cedar (see below). The plugin installs the hooks.

# 3. Create the signing key once (protect-mcp 0.32.4 sign does not create it).
#    An existing key is never replaced. See references/receipt-format.md to rotate.
if [ ! -e ./protect-mcp.key ]; then
  d=$(mktemp -d) && npx protect-mcp@0.32.4 init --dir "$d" && mv "$d/keys/gateway.json" ./protect-mcp.key
fi
chmod 600 ./protect-mcp.key
echo "/protect-mcp.key" >> .gitignore

# 4. Use Claude Code normally. Every tool call is now policy-evaluated
#    and produces a signed receipt in ./receipts/

Hook Configuration

Installing the plugin adds both hooks from hooks/hooks.json. Each hook runs a script bundled with the plugin:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/evaluate.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/sign.sh" }
        ]
      }
    ]
  }
}

Claude Code passes the hook event to the command as JSON on stdin and does not set TOOL_NAME or TOOL_INPUT variables. evaluate.sh reads tool_name and tool_input from that payload and passes them to protect-mcp as flags; sign.sh reads tool_name only, preserving tool-only receipt coverage. The signing hook keeps stdout empty, checks the CLI summary, and reports signer failures on stderr. Set PROTECT_MCP_POLICY, PROTECT_MCP_RECEIPTS, and PROTECT_MCP_KEY to change the default paths. When the policy file is missing, the PreToolUse hook prints a warning to stderr and allows the call.

What each hook does

PreToolUse — Runs BEFORE the tool executes. Evaluates the tool call against your Cedar policy file. If Cedar returns deny, the hook exits with code 2 and Claude Code blocks the tool call entirely.

PostToolUse runs AFTER the tool completes. It signs a receipt that names the tool and appends it to ./receipts/receipts.jsonl. This hook does not pass the tool input or output to the signer.

Cedar Policy File

Create ./protect.cedar at the project root:

// Read-only tools: one rule can name several tools in `when`. Add WebFetch
// with your own URL rule.
permit (principal, action == Action::"MCP::Tool::call", resource) when {
    resource == Tool::"Read" || resource == Tool::"Glob" || resource == Tool::"Grep"
};

// Safe commands only; git limited to read subcommands
permit (principal, action == Action::"MCP::Tool::call", resource == Tool::"Bash") when {
    context has input && context.input has command &&
    (context.input.command like "git status*" || context.input.command like "git diff*" ||
     context.input.command like "git log*" || context.input.command like "git show*" ||
     context.input.command like "npm*" || context.input.command like "ls*" ||
     context.input.command like "cat*" || context.input.command like "echo*" ||
     context.input.command like "pwd*" || context.input.command like "test*")
};

// No chaining (`&` also denies `2>&1`), `$` expansion, redirection (`>` or
// `<`, which covers `<(`), file output (`git diff --output`), or rm -rf
forbid (principal, action == Action::"MCP::Tool::call", resource == Tool::"Bash") when {
    context has input && context.input has command &&
    (context.input.command like "*;*" || context.input.command like "*&*" ||
     context.input.command like "*|*" || context.input.command like "*$*" ||
     context.input.command like "*`*" || context.input.command like "*>*" ||
     context.input.command like "*<*" || context.input.command like "*\n*" ||
     context.input.command like "*--output*" || context.input.command like "*rm -rf*")
};

// Writes only inside the project (paths are absolute), never via `..`
permit (principal, action == Action::"MCP::Tool::call", resource) when {
    (resource == Tool::"Write" || resource == Tool::"Edit") &&
    context has input && context.input has file_path &&
    context.input.file_path like "/path/to/project/*"
};
forbid (principal, action == Action::"MCP::Tool::call", resource) when {
    (resource == Tool::"Write" || resource == Tool::"Edit") &&
    context has input && context.input has file_path &&
    (context.input.file_path like "*/../*" || context.input.file_path like "*/..")
};

String matching is best-effort: like checks the raw string, not a resolved path, and an npm* permit runs arbitrary code, so it is only as safe as the project's scripts.

Verification

Verify every receipt against the public key in ./protect-mcp.key:

PUB=$(node -p 'JSON.parse(require("fs").readFileSync("./protect-mcp.key")).publicKey')
npx @veritasacta/verify@0.11.1 --replay-chain ./receipts/receipts.jsonl --key "$PUB"
# Exit 0 = every receipt verified
# Exit 1 = a receipt failed (tampered, wrong key, or malformed line)
# Exit 2 = the file could not be read

The plugin's slash commands do the same inside Claude Code. /verify-receipt takes one receipt in its own file, e.g., from tail -n 1 ./receipts/receipts.jsonl > receipt.json.

/verify-receipt receipt.json
/audit-chain --last 20

Receipt Format

Each receipt is one line of ./receipts/receipts.jsonl. See references/receipt-format.md for a sample.

  • Ed25519 signatures (RFC 8032) over the canonical payload
  • JCS canonicalization (RFC 8785) before signing
  • Signed public key in the payload; supply a trusted key with --key
  • Hash link to the previous receipt, checked during replay

The verifier detects broken links between surviving receipts, including interior deletion or reordering. A truncated tail and deletion or reordering within the legacy portion of a mixed log can go undetected. Editing signed contents still fails signature verification. Keep an externally retained checkpoint or copy to check completeness.

Why This Matters

BeforeAfter
"Trust me, the agent only read files"Cryptographically provable: every Read logged and signed
"The log shows it happened"The receipt proves it happened, and no one can edit it
"You'd have to audit our system"Anyone can verify every receipt offline
"Logs might be different by now"Ed25519 signatures lock the record at signing time

Standards

  • Ed25519 — RFC 8032 (digital signatures)
  • JCS — RFC 8785 (deterministic JSON canonicalization)
  • Cedar — AWS's open authorization policy language
  • IETF draft — draft-farley-acta-signed-receipts

Related

rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall