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 | IETF Internet-Draft | Live demo: 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 .

Related MCP server: verify-mcp

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

Standards & IP

• IETF Internet-Drafts:

  • draft-farley-acta-signed-receipts-01 — Signed Decision Receipts for Machine-to-Machine Access Control

  • draft-farley-acta-knowledge-units-00 — Knowledge Units for Multi-Model Deliberation

  • Source: VeritasActa/drafts

• Patent Status: 4 Australian provisional patents pending (2025-2026) covering decision receipts with configurable disclosure, tool-calling gateway, agent manifests, and portable identity

• Verification: Apache-2.0 — npx @veritasacta/verify --self-test

• Microsoft AGT Integration: PR #667 — Cedar policy bridge for Agent Governance Toolkit

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