protect-mcp-setup

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.7.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.7.4 init --dir "$d" && mv "$d/keys/gateway.json" ./protect-mcp.key
fi
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, because the 0.7.4 signer records nothing else. 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. protect-mcp 0.7.4 does
not record the tool input or output.

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.9.2 --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 all fields but signature
• JCS canonicalization (RFC 8785) before signing
• No public key in the receipt, so pass it with --key
• No link to the previous receipt, so a deleted line goes undetected

Why This Matters

Before	After
"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

• npm: protect-mcp
• Verify CLI: @veritasacta/verify
• Source: github.com/ScopeBlind/scopeblind-gateway
• Protocol: veritasacta.com
• Integrations: Microsoft Agent Governance Toolkit (PR #667), AWS cedar-policy/cedar-for-agents (PR #64)