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 protect-mcp@0.25.0 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:

1. coordination.prepare_task({request_id, draft}) saves an unsigned draft and returns a private review link for you. Keep the same request_id when retrying. The draft contains a title, goal, and optional proposed limits, assumptions, and private preferences. It creates no room or human authority.
2. Review the draft in the browser, edit it, and sign your own limits. Invite the other person, who signs their own limits independently. Separately authorize your agent’s negotiation connection. Review links expire after 30 minutes; possession does not give the agent payment or approval powers.
3. coordination.inspect_task_request({request_id}) checks that review. coordination.claim_task_connection({request_id}) claims the exact authorized grant and returns a connection_id. Then call coordination.inspect_negotiation({connection_id}) before proposing or testing.
4. Both humans approve one exact tested plan. The original organizer creates the separate task and may explicitly authorize the same agent to execute it. coordination.check_handoffs({connection_id}) discovers that authorization; coordination.claim_execution_connection({connection_id, handoff_id}) saves a new execution connection. Inspect its returned connection_id before submitting payments. The negotiation token never becomes a payment token.

Every scoped tool in the profile requires an explicit connection_id; use coordination.connections to list saved connections without credentials. The profile preserves tokens before claiming so an uncertain reply can be recovered with the same IDs. Initial pairing windows last at most ten minutes. If that window or a grant expires, the original person must explicitly reconnect the same profile under current limits. Missing profiles require fresh authorization. A profile holds at most 50 requests and 50 connections; keep it private.

Existing one-room connections below still work. Import one with coordination agent import --profile FILE --config OLD_PRIVATE_CONFIG after setting up the profile. Import preserves its scope and cannot reconstruct a private agent key discarded by older pairing; that connection cannot claim a same-key execution handoff.

Draft text and private instructions are sent to ScopeBlind. Your agent’s model provider may receive tool results, including your own authorized private brief. A hosted assistant receives its own principal’s brief plus shared records. Neither profile setup nor a stopped client runs a background agent or model.

Make exact decisions on another device

From a task on the original authorized browser, choose Continue on another device. Open or scan its link on your phone, request access, and compare the shown code on both devices. The original browser signs the exact phone key, room, permissions, and expiry. A link or QR code alone grants no authority; each device retains its own private signing key.