protect-mcp

Enterprise security gateway for MCP servers and Claude Code hooks. Signed receipts, Cedar policies, and swarm-aware audit trails.

Integrated into [Microsoft Agent Governance Toolkit](https://github.com/microsoft/agent-governance-toolkit) (Tutorial 33 merged; sb-runtime integration PR #1202 open) | [IETF Internet-Draft](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/) (draft-02 pending) | [AGT Integration Profile](https://github.com/VeritasActa/agt-integration-profile) | [Live demo: acta.today/wiki](https://acta.today/wiki)

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.

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
  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.

Verified Knowledge Base (acta.today/wiki)

protect-mcp's receipt signing powers the world's first verified multi-model knowledge base at acta.today/wiki.

Every Knowledge Unit is produced by 4 frontier models deliberating in 3 adversarial rounds, with Ed25519 receipts on every model response. The current roster:

Every KU is independently verifiable: npx @veritasacta/verify receipt.json

Ecosystem Integrations

Verification properties

protect-mcp receipts are offline-verifiable and tamper-evident via @veritasacta/verify:

• No server contacted during verification
• Math runs against a public key provided externally (--key / --jwks / --trust-anchor)
• Any tampering breaks the signature or chain; exit 1 is proven modification
• No vendor trust — only Ed25519 (RFC 8032) and JCS (RFC 8785) are in the verification path

What this does not provide: issuer-blind / unlinkable verification in the VOPRF sense. The Ed25519 signature identifies the signer. If you need verification where the verifier cannot link multiple presentations to the same signer (privacy-preserving metered authorization, anonymous credentials, unlinkable rate limiting), that's a separate primitive with its own stack:

• Protocol and verifier: open-source under Veritas Acta, Apache-2.0. Anyone can verify, no vendor dependency.
• Production issuer (commercial): ScopeBlind sells the managed VOPRF issuance API (scopeblind.com) — the revenue product that sits behind the open protocol. You can run your own issuer, but the cryptographic correctness, key rotation, and metering are hard enough that most teams use the managed service.

protect-mcp doesn't require VOPRF for decision auditability — the Ed25519 receipts cover that. The VOPRF product solves a different problem (privacy-preserving verification at scale) for teams that need it.

Standards & IP

• IETF Internet-Drafts:
• draft-farley-acta-signed-receipts — Signed Decision Receipts for Machine-to-Machine Access Control (draft-02 pending with Security Considerations on key distribution)
• draft-farley-acta-knowledge-units-00 — Knowledge Units for Multi-Model Deliberation
• Source: VeritasActa/drafts
• Patent Status: 5 Australian provisional patents pending (2025-2026) covering decision receipts with configurable disclosure, tool-calling gateway, agent manifests, portable identity, and Sigil visual commitments
• Verification: Apache-2.0 — npx @veritasacta/verify --self-test
• Microsoft AGT Integration: Tutorial 33 merged (PR #1197); sb-runtime integration (PR #1202) pending review; AGT Integration Profile formalizes the conformance surface.

Related Repositories

Contributing

Issues and pull requests are welcome. Please open an issue first for significant changes.

• Bug reports: Include the protect-mcp version, Node.js version, and steps to reproduce
• Cedar policies: Share reusable policies via PR to the policies/cedar/ directory
• Integration examples: Add to ScopeBlind/examples

License

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

scopeblind.com · npm · veritasacta.com · IETF Drafts