protect-mcp

Fail-closed Cedar policy gate plus signed receipts for AI agent tool calls.

protect-mcp is a gate that sits in front of an AI agent's tool calls. It evaluates each call against a Cedar policy, blocks what breaks the rules before it runs, and signs an offline-verifiable Ed25519 receipt of every decision. The configured gateway runs locally and sends no decision telemetry. The separate coordination adapter connects to ScopeBlind’s hosted collaboration service; its requests and returned records have the data path described below. Both are MIT licensed.

For shared repository work, use client projects: people agree on the brief and limits, agents prepare reviews, and both people approve an exact version before the owner's receiver can change the repository. The repository workflow below includes setup and the five bounded agent tools.

Why it is different

• Fail-closed by default. On any policy error, a missing engine, or an evaluation failure, the decision is DENY. The gate never silently allows. An observe mode exists for shadow rollout, but even there a call that would be blocked is flagged would_deny: true, so a failure is never silent.
• It proves its own restraint. serve --enforce and doctor run a startup self-test and refuse to arm the gate unless they can show that a known-forbidden action is actually denied. A gate that cannot prove it denies does not start.
• Every decision is a receipt anyone can verify. Decisions are Ed25519-signed and verifiable offline with @veritasacta/verify. Signature verification needs no network lookup. Claims about execution still depend on the identified gate operator.

Quickstart: install to first useful proof

# 1. Generate an Ed25519 keypair, config template, and sample policy.
npx protect-mcp init

# 2. Print a shadow-mode client configuration, then apply it in your MCP host.
#    This command prints configuration and exits; it does not launch the server.
npx protect-mcp wrap -- node your-mcp-server.js

# 3. Reopen the host and use its tools, then inspect the local-only dashboard.
npx protect-mcp dashboard --open

# 4. Draft a reviewable policy from observed calls.
npx protect-mcp recommend --write

# 5. When reviewed, restart the wrapper in enforce mode with that policy.
npx protect-mcp --policy protect-mcp.recommended.json --enforce -- node your-mcp-server.js

For Claude Desktop, run a dry-run config patch first, then apply it:

npx protect-mcp wrap --claude-desktop
npx protect-mcp wrap --claude-desktop --write
npx protect-mcp dashboard --open

The dashboard binds to 127.0.0.1, reads only local log/receipt files, and does not upload anything. Use npx protect-mcp connect only if you explicitly want a hosted ScopeBlind dashboard.

The gate as an MCP server

If you would rather call the gate as tools than wire the Claude Code hooks, run it as an MCP server:

npx protect-mcp mcp

It speaks MCP over stdio and exposes four read-only tools, the whole loop:

• evaluate_action: decide a proposed tool call against an inline Cedar policy, fail-closed (any policy error is DENY). Returns { allowed, decision, reason, policy_digest }.
• sign_decision: turn a decision into an Ed25519 signed receipt (a denial signs a gateway_restraint, an allow a decision_receipt). Returns the receipt and its public key; generates an ephemeral key if you do not supply one.
• verify_receipt: verify a signed receipt offline against a public key. Returns { valid, error, type, kid, issuer }.
• self_test: prove it, no inputs. A known-forbidden action is denied, then a signed receipt round-trips and a tampered copy fails.

Point any MCP host at it, for example Claude Desktop:

{
  "mcpServers": {
    "protect-mcp": { "command": "npx", "args": ["-y", "protect-mcp", "mcp"] }
  }
}

Receipts are byte-compatible with the ones the gate signs at runtime, so a receipt minted here uses the same Acta envelope. Verification capabilities and canonicalization compatibility depend on the verifier version; use the gateway's verifyReceipt API for the conformance behavior described below.

Receipt canonicalization compatibility

This source tree fixes the integer-key ordering defect present through 0.14.0: signatures and chain hashes now use direct JCS member emission, retaining the gateway's ASCII object-key profile. Numeric-looking keys such as "10" precede "2", including inside nested objects. Non-JSON values and invalid Unicode are rejected.

Ordinary JSON receipts whose encodings are unchanged continue to verify. Historical receipts signed with the old numeric-key order are reported as legacy_non_jcs_signature; strict verification does not call them valid JCS. For an explicit historical compatibility check, use verifyReceipt(receipt, publicKey, { allowLegacyNumericKeys: true }) and inspect the canonicalization and warning fields. Its hash is then the original historical hash. Preserve original receipts and chain links: recomputing an old numeric-key receipt with receiptHash now produces its JCS hash and can break the historical chain. These changes are included in 0.15.0.

Start with your agent, then authorize each task

Version 0.25.0 includes a reusable agent profile. Open Start through your agent for the setup command with the service’s displayed authority key. Check that key against a trusted source before connecting. For example:

npx --yes [email protected] coordination agent setup \
  --client claude-code \
  --profile ~/.scopeblind/agent.json \
  --endpoint https://scopeblind.com/api/coordination \
  --authority-key PINNED_64_HEX_AUTHORITY_KEY

Use --client codex or --client json for those registration instructions. Setup prints configuration; apply it in your client, then reopen that client. The private profile holds an agent key and separately scoped connections, with file permissions 600. Setup grants no task permissions and copies no human browser key. The registered server runs coordination agent --profile FILE.

Ask your agent to prepare a shared invoice task for your review. The tool flow is: