protect-mcp

A policy check that sits between your AI agent and the tools it calls. Every tool call is evaluated against a rule you wrote. Every decision is signed.

What it does, in plain English

When an AI agent (Claude Code, Cursor, a custom LangChain app, anything that uses the Model Context Protocol) wants to run a command, edit a file, or call an API, protect-mcp intercepts that request before it executes:

1. Checks a policy. You write rules in Cedar — the same policy language AWS uses for IAM. Rules like "never allow rm -rf /", "only allow Bash during working hours", or "require human approval for anything touching production."
2. Returns a decision. allow, deny, or request_approval. The agent framework respects the decision — if it's deny, the tool call doesn't run.
3. Signs a receipt. An Ed25519-signed, hash-chained record of the decision, written to .receipts/. Verifiable offline by anyone with the public key. When your auditor asks "what did that agent do on 2026-03-14?" you have cryptographic proof — not a log file you might have tampered with.

You install it once. Your agent keeps working the same way. The difference: every action it takes is now policy-checked and audit-evidenced.

Who this is for

• Developers using Claude Code / Cursor / Cline who want "don't let the agent delete my repo" enforced rather than hoped for.
• Security teams shipping agents to engineering who need a portable policy layer that travels across frameworks.
• Compliance teams who need tamper-evident evidence of what agents did, verifiable without trusting the vendor.

How it relates to sb-runtime

protect-mcp is a library — it sits inside your agent framework and gates tool calls cooperatively. Right tool when you own the agent's code and trust its framework to honour decisions.

sb-runtime is the companion binary that wraps the whole agent process in an OS-level sandbox (Landlock + seccomp on Linux). It enforces decisions at the kernel layer — the agent can't ignore them even if it tried. Use sb-runtime when you're running an agent you didn't write, or when you want belt-and-braces defence in depth:

┌─────────────────────────────────────────────────┐
│  sb-runtime   ← OS refuses forbidden syscalls   │
│  ┌───────────────────────────────────────────┐  │
│  │  agent process (Claude Code, Python, …)   │  │
│  │  ┌─────────────────────────────────────┐  │  │
│  │  │  protect-mcp                        │  │  │
│  │  │    ← Cedar decides per tool call,   │  │  │
│  │  │      receipts every decision        │  │  │
│  │  └─────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

One-liner: protect-mcp is the policy hook inside your agent. sb-runtime is the OS sandbox around it. You want both.

Quick Start — Claude Code

Two commands. Every tool call is receipted.

# 1. Generate hooks, keys, Cedar policy, and /verify-receipt skill
npx protect-mcp init-hooks

# 2. Start the hook server
npx protect-mcp serve

Open Claude Code in the same project. Every tool call is now intercepted, evaluated, and signed.

To also connect to the ScopeBlind dashboard in one step:

npx protect-mcp quickstart --connect

Creates a free ScopeBlind dashboard and configures receipt upload automatically. No signup required. Free up to 20,000 receipts/month.

What init-hooks creates

Architecture

Claude Code  →  POST /hook  →  protect-mcp (Cedar + sign)  →  response
                                    ↓
                            .protect-mcp-log.jsonl
                            .protect-mcp-receipts.jsonl

• PreToolUse: synchronous Cedar policy check → deny blocks the tool
• PostToolUse: async receipt signing → zero latency impact
• deny is architecturally final — it cannot be overridden by the model or other hooks

Endpoints

Verify receipts

# Inside Claude Code:
/verify-receipt

# From terminal:
curl http://127.0.0.1:9377/receipts/latest | jq .
npx protect-mcp receipts

# Check policy suggestions:
curl http://127.0.0.1:9377/suggestions | jq .

Quick Start — MCP Server Wrapper

Wrap any stdio MCP server as a transparent proxy:

# Shadow mode — log every tool call, enforce nothing
npx protect-mcp -- node my-server.js

# Enforce mode with policy
npx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js

# Generate keys + config template
npx protect-mcp init

How It Works

protect-mcp evaluates every tool call against a policy (JSON, Cedar, or external PDP), signs the decision as an Ed25519 receipt, and logs the result.

Two integration modes:

Three policy engines:

Swarm Tracking

In multi-agent sessions, protect-mcp automatically tracks the swarm topology.

11 hook events handled:

Each receipt includes:

• swarm.agent_id, swarm.agent_type, swarm.team_name
• timing.tool_duration_ms, timing.hook_latency_ms
• payload_digest (SHA-256 hash for payloads >1KB)
• deny_iteration (retry count after denial)
• sandbox_state (enabled/disabled/unavailable)
• OpenTelemetry otel_trace_id and otel_span_id

Policy File

{
  "default_tier": "unknown",
  "tools": {
    "dangerous_tool": { "block": true },
    "admin_tool": { "min_tier": "signed-known", "rate_limit": "5/hour" },
    "read_tool": { "require": "any", "rate_limit": "100/hour" },
    "*": { "rate_limit": "500/hour" }
  },
  "signing": {
    "key_path": "./keys/gateway.json",
    "issuer": "protect-mcp",
    "enabled": true
  }
}

Cedar Policies

Cedar deny decisions are authoritative — they cannot be overridden.

// Allow read-only tools
permit(
  principal,
  action == Action::"MCP::Tool::call",
  resource == Tool::"Read"
);

// Block destructive tools
forbid(
  principal,
  action == Action::"MCP::Tool::call",
  resource == Tool::"delete_file"
);

When a tool is denied, protect-mcp auto-suggests the minimal Cedar permit() rule via GET /suggestions.

CVE-Anchored Policy Packs

Each prevents a real attack:

Cedar equivalents available in policies/cedar/.

MCP Client Configuration

Claude Desktop

{
  "mcpServers": {
    "my-protected-server": {
      "command": "npx",
      "args": [
        "-y", "protect-mcp",
        "--policy", "/path/to/protect-mcp.json",
        "--enforce",
        "--", "node", "my-server.js"
      ]
    }
  }
}

Cursor / VS Code

Same pattern — replace the server command with protect-mcp wrapping it.

CLI Commands

Commands:
  serve             Start HTTP hook server for Claude Code (port 9377)
  init-hooks        Generate Claude Code hook config + skill + sample Cedar policy
  quickstart        Zero-config onboarding: init + demo + show receipts
  connect           Link to ScopeBlind dashboard (creates sandbox if needed)
  init              Generate Ed25519 keypair + config template
  demo              Start a demo server wrapped with protect-mcp
  doctor            Check your setup: keys, policies, verifier, connectivity
  trace <id>        Visualize the receipt DAG from a given receipt_id
  status            Show tool call statistics from the decision log
  digest            Generate a human-readable summary of agent activity
  receipts          Show recent persisted signed receipts
  bundle            Export an offline-verifiable audit bundle
  simulate          Dry-run a policy against recorded tool calls
  report            Generate a compliance report from an audit bundle

Options:
  --policy <path>   Policy/config JSON file
  --cedar <dir>     Cedar policy directory
  --enforce         Enable enforcement mode (default: shadow)
  --port <port>     HTTP server port (default: 9377 for serve)
  --verbose         Enable debug logging

Decision Logs

Every tool call emits structured JSON to stderr:

[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"cedar_allow","policy_digest":"a1b2c3...","mode":"enforce","hook_event":"PreToolUse","timing":{"hook_latency_ms":1},"otel_trace_id":"..."}

When signing is configured, a signed receipt is persisted to .protect-mcp-receipts.jsonl.

Audit Bundles

npx protect-mcp bundle --output audit.json

Self-contained offline-verifiable bundle with receipts + signing keys. Verify with npx @veritasacta/verify.

Dashboard

protect-mcp works fully offline. Optionally connect to the ScopeBlind dashboard for:

• Real-time receipt visualization
• Abuse alerts and anomaly detection
• Compliance export and audit bundles
• Usage analytics

Free tier: 20,000 receipts/month. No credit card required.

scopeblind.com/pricing

Interoperability

The receipt format is independently implemented and verified across multiple systems:

Verify any receipt from any implementation:

npx @veritasacta/verify receipt.json --key <public-key-hex>
# Exit 0 = valid, 1 = tampered, 2 = malformed

Standards & IP

• IETF Internet-Draft: draft-farley-acta-signed-receipts-01
• Patent Status: 4 Australian provisional patents pending (2025-2026)
• Cedar WASM: PR #64 merged + PR #73 (RequestGenerator, pending review)

What's New in v0.5.3

• quickstart --connect: Auto-create dashboard sandbox and configure receipt upload
• connect subcommand: Link an existing setup to the ScopeBlind dashboard
• Anonymous install telemetry (opt-out: PROTECT_MCP_TELEMETRY=off)
• Improved Cedar WASM detection

Cybersecurity: Vulnerability Disclosure Receipts

protect-mcp provides the infrastructure for receipt-signed vulnerability disclosure workflows. When AI security agents (Claude Code Security, Mythos, or similar) discover vulnerabilities, every step of the disclosure lifecycle can produce a signed, chain-linked receipt:

DISCOVER → DISCLOSE → PATCH → DEPLOY
(Each step: Ed25519-signed, chain-linked, Cedar policy-bound)

Cedar policies govern what the scanning agent is allowed to do:

• CAN: scan code, report findings internally
• CANNOT: disclose externally or deploy patches without human approval
• MUST: escalate critical findings to humans

See the security vulnerability disclosure example for a complete working implementation with Cedar policies and example receipt chains.

Related: Vulnerability Disclosure Receipt Design

Examples

See complete working examples at github.com/ScopeBlind/examples:

• Claude Code hooks — receipt signing for every tool call
• Security vulnerability disclosure — receipt-signed disclosure lifecycle with Cedar governance
• MCP server signing — Cedar WASM policy engine with audit bundles

ScopeBlind Dashboard

protect-mcp works fully offline, forever, for free. For teams that want visibility across agents, ScopeBlind offers a hosted dashboard:

npx protect-mcp connect

No signup required for free tier. No card upfront.

Dashboard | Docs | Pricing

Telemetry

protect-mcp sends a single anonymous install beacon on first run (package name, version, OS, Node version). No PII. Disable with:

PROTECT_MCP_TELEMETRY=off

License

MIT — free to use, modify, distribute, and build upon without restriction.

Built by ScopeBlind | npm | GitHub | IETF Draft