Agent Custody MCP Server

agent-custody

Stop your coding agent from running destructive commands, and keep a signed record that a reviewer can check.

This is for engineers who run Claude Code against repositories and systems that touch production. One command adds a hook to Claude Code. The hook checks each shell command, file edit, and MCP tool call against a deny list before the call runs. The starter list covers force push, rm -rf on / and ~, terraform destroy, and drop database.

npm install -g @agent-custody/receipts
agent-custody init claude-code

The command needs Node 22. To try it once, run npx @agent-custody/receipts init claude-code. Do not keep the npx form: npm can clear its cache, and the hooks then stop working. The command makes an agent key, writes a starter deny list, and registers the hooks in .claude/settings.local.json of the current directory. It starts in observe mode: it blocks nothing until you say so. Details and options: Setup for Claude Code.

What you see

Work in Claude Code as usual. The hook signs a record of each shell command, file edit, and MCP tool call. The record is called a receipt. Then run the report. It checks the signature of every receipt, and it lists the calls that the deny list would have stopped.

agent-custody report --config ~/.config/agent-custody/sdk.json

would have denied 2 calls (the policy recorded each one and blocked nothing)

  Bash: git push --force origin main
    reason:  force push rewrites shared history (git push --force-with-lease is allowed)
    rule:    forbid(principal, action == Action::"Bash", resource) when { context.args has command && ( context.args.command like "*git push*--force *" || context.args.command like "*git push*--force" || context.args.command like "*git push -f*" || context.args.command like "*git push* -f" ) } [policy1]
    receipt: 191e1095-db76-45fc-82d4-3dc9a6e14023  (2026-11-02T11:15:18.824Z)

  Bash: terraform destroy -auto-approve
    reason:  terraform destroy deletes infrastructure
    rule:    forbid(principal, action == Action::"Bash", resource) when { context.args has command && context.args.command like "*terraform destroy*" } [policy5]
    receipt: 6f4c2455-b578-4a0f-b7ed-7fee177e5a9b  (2026-11-02T11:15:18.827Z)

Checked 4 receipts: 4 verified, 0 did not verify.

To enforce this policy, remove the "mode": "observe" line from ~/.config/agent-custody/sdk.json. A denied call is then blocked before it runs.

That output comes from tutorial 36, with the path of sdk.json shortened. To enforce the list, remove the "mode": "observe" line. A denied call then stops before it runs.

An incident replay

A coding agent runs terraform destroy. A script plays the session in enforce mode. It needs no model and no network, and it runs no destructive command.

git clone https://github.com/svayatta/agent-custody
cd agent-custody && bun install
cd packages/receipts && node examples/38-incident-replay.ts

• terraform plan runs. The hook records an executed receipt.
• terraform destroy -auto-approve is denied before it runs. Claude Code shows the agent agent-custody denied this call: terraform destroy deletes infrastructure (rule policy5, receipt 980d078f-2922-42b7-a5de-de3b99b00997).
• rm -rf ~ is denied the same way.
• A reviewer holds the agent's public key and the receipt files. They verify the three receipts offline. The same check with a key that is not the agent's fails for the terraform destroy receipt.

The full output is on the page An incident replay.

What the hook does not stop

The hook stops a shell command, a file edit, or an MCP tool call that the agent makes. Read these limits before you rely on it.

• A credential in the agent's environment goes around the hook. If the shell of the agent holds a cloud key or a database password, a process that the agent starts can use it. The hook does not stop that process.
• The starter list matches the text of a command. It catches the plain form of each command. It is not a sandbox.
• Some tools are not seen. The hook matches Bash, Write, Edit, MultiEdit, NotebookEdit, and MCP tools. It does not see Read, Grep, Glob, WebFetch, WebSearch, or Task. The starter deny list has rules for Bash only.
• The record is the agent's own report. Every field is claimed. The signature shows that the record did not change after the hook wrote it. It does not show that the hook saw every call.

To cover more, keep production credentials out of the agent's environment, and put a gateway between the agent and the tools that touch production. The threat model lists what each part defends, and what it does not. No independent witness runs yet, and the hosted log is not anchored on mainnet yet.

Advanced

Everything above is the Claude Code hook. The rest of the product is below and on the advanced page: the gateway with grants and Cedar policy, the transparency log, the state package for agent memory, the hosted log, and the other frameworks and languages.

What each piece is for, and when you need it

Each part exists because a specific thing goes wrong without it. Use the table to decide what to turn on.

The rule of thumb: record everything with the SDK, enforce the consequential calls with the gateway, log remotely once a receipt has an audience outside the team, put beliefs in the ledger the moment memory outlives a session, and turn on quarantine, forget, and holds the moment that memory holds anything about a person.

The SDK and the state ledger, step by step

Node 22 or later. Both packages ship compiled JavaScript with type declarations.

npm install @agent-custody/receipts @agent-custody/state

1. Give the agent's process a signing key and a config. The key signs every receipt. The config says where receipts and the log go.

npx @agent-custody/receipts keygen --dir keys --name app

{ "agentId": "support-bot", "identity": { "keyFile": "keys/app.key" }, "receiptsDir": "receipts", "logFile": "log.jsonl" }

2. Record a tool call as a receipt. Wrap the functions the agent calls, or record a call explicitly. Either way a signed receipt lands in receipts/ and a leaf in the Merkle log.

import { createSdkIssuer, loadSdkConfig } from "@agent-custody/receipts";

const issuer = createSdkIssuer(loadSdkConfig("./sdk.json"));

const lookup = issuer.wrap("crm.lookup", async (args: { id: string }) => crm.lookup(args));   // records every call
const customer = await lookup({ id: "acct:42" });

const bundle = await issuer.record({ tool: "crm.lookup", args: { id: "acct:42" } }, { status: "executed", result: customer });   // or record one by hand and keep the bundle

3. Verify it, offline. Anyone with the public key and a copy of the log can check the signature, the statement, and the inclusion proof. No access to the agent or the issuer needed.

import { loadPublicKey, verifyBundle } from "@agent-custody/receipts";

verifyBundle(bundle, { issuerKeys: [loadPublicKey("keys/app.pub")], principalKeys: [], logFile: "log.jsonl" }).ok;   // true

npx @agent-custody/receipts verify receipts/<id>.json --issuer-key keys/app.pub --log log.jsonl    # the same check from the shell

4. Record what the agent now believes, citing the receipt. The ledger is bitemporal: it knows when a fact was true and when the agent learned it. A belief points back at the receipt that produced it.

import { receiptIdOf } from "@agent-custody/receipts";
import { Ledger } from "@agent-custody/state";

const ledger = new Ledger("./ledger.jsonl"); // or "./ledger.sqlite", or "postgres://…"
const belief = await ledger.assert({ subject: "acct:42", predicate: "plan", value: customer.plan, space: "org", actor: "support-bot", source: { receiptId: receiptIdOf(bundle) } });

5. When a belief is wrong, undo it without losing the record. Retract removes it from the present, keeps it visible to questions about the past, and restores whatever it had superseded. The receipt id says exactly which call produced the bad belief.

await ledger.retract({ factId: belief.fact.factId, actor: "user:admin", reason: "CRM lookup returned a stale plan" });
await ledger.asOf({ subject: "acct:42" });                                                  // [] now
await ledger.asOf({ subject: "acct:42", validAt: earlier, txAt: earlier });                  // still shows what was believed then
await ledger.history(belief.fact.factId);                                                    // assert, retract, with actors and reasons

This whole loop is one runnable file, packages/state/examples/02-receipt-to-belief.ts, executed by the test suite.

Where to go next

• Enforce instead of record: put the gateway between the agent and its MCP tools, its REST APIs, or any agent it delegates to over A2A, with a signed delegation grant and a Cedar policy. Denied calls never reach the tool and still get a receipt. packages/receipts/docs/usage.md
• Hook an existing framework: Claude Code and the Claude Agent SDK, the OpenAI Agents SDK, the Vercel AI SDK, LangChain, OpenClaw, DeepSeek Harness; in Python also CrewAI, Google ADK, and Hermes Agent. packages/receipts/docs/sdk.md
• Write policies, for tools and for memory, with tested examples, and read what a verified receipt does and does not prove. policies.md, verification.md
• Answer a security questionnaire with a file: which artefact supplies evidence for which SOC 2, ISO 27001, UK GDPR, EU AI Act, FINRA, MAS, Colorado, DORA, CSA AICM, OWASP, and ISO 42001 requirement, with dates, primary sources, and what a receipt does not supply. compliance.md
• Give a security reviewer the attacker's view: who could make a receipt false, what stops them, and what is not defended. threat-model.md
• Log to a server the operator does not control, so tree heads are signed by a key that is not yours. verification.md
• Verify a receipt in the browser, nothing uploaded, and check a second implementation against the published conformance vectors. agent-custody.dev/verify, vectors
• Prove a log was never rewritten: keep any receipt's tree head, later audit that the log still extends it. verification.md
• Run the console for a gateway: config, tools, receipts with a verdict each, a policy editor that replays recorded calls before it saves, and grant revocation, as a service of its own. console.md.
• Configure the gateway: who may use which tools, where the tools live, a worked example, and agent-custody check to validate a config before it starts. configuration.md.
• Run one shared gateway for every agent on a host or cluster: a container image for amd64 and arm64, compose, Kubernetes, and systemd recipes, a starter config. deploy/gateway.
• See how it fits together, with diagrams: what runs on the customer's side, what is hosted, the sequence of a call, onboarding, revocation, and verification. Architecture.
• Where each piece runs, sized, with what interception does not reach. Deployment. What each release changed: changelog.
• Register a tenant on the hosted log at app.agent-custody.dev and get a log and a first key at once: free for ten thousand appends a month, $50 a month for a million, a dashboard with usage against the plan, keys, and every action taken on the tenant, and an export that takes everything with you.
• The reference at docs.agent-custody.dev: every feature, and the exact request and response of every function, endpoint, MCP tool, and command.
• Want a log run by someone who is not you? deploy/ has the container, a docker compose file for one VM, and Kubernetes manifests to run it on a machine the operator does not control; or take a tenant on the one we run, at log.agent-custody.dev, on the Free or Team plan.
• Agents in Python, Go, Java, Rust, or anything else: the gateway is an MCP server and needs nothing from your language; for in-process receipts run the sidecar and use the Python package or a forty-line client. sdk.md
• Step-by-step examples in the receipts package and more in the state package: receipts tutorials, state examples.

Packages

Receipts are the unit. State is the ledger of what the agent came to believe from them. Both append to the same kind of signed log and are checked by the same kind of verifier.

Try the live Codex recovery demo: a real agent handles a support request using incorrect customer memory, then an operator traces possible consequences, approves corrections and simulated credit compensation, and verifies the evidence.

Agent sessions in this repository

A Claude Code session in this repository can run under custody. On a machine with the recording config, each shell command, file edit, and MCP tool call becomes a signed receipt, and its hash goes to our tenant on the hosted log within seconds. A force push is refused by policy, and the refusal is a receipt too. A machine without that config records and refuses nothing, so the tenant does not cover all the work in this repository. The hook is committed in .claude/, the receipts and keys stay outside the repository, and agent-custody.dev/custody shows the live tenant and sample receipts anyone can verify.

Security

Report a vulnerability privately to partha@charioteerconsulting.com; SECURITY.md has the scope, the response times, and how keys and tokens are protected.

Working in the repository

bun install                         # one install for the whole workspace
bun run test                        # every package
bun run build                       # dist/ for every package, what consumers install
bun run test:python                 # the Python package, with uv; needs node for the sidecar
bun run ci                          # everything the GitHub workflow runs; the pre-push hook runs it before any push to main
bun run demo                        # the receipts demo: keys, grant, policy, tool calls, verification, a tampering attempt

Everything runs on plain Node 22 or later. No build step. Package-level commands, such as the CLI and the tutorials, run from inside that package's directory; each package README says how. CONTRIBUTING.md has the rules for a change, a release, and a publish.

Layout

package.json          workspace root: typecheck, test, and demo across packages
tsconfig.base.json    compiler options shared by every package
action.yml            the GitHub Action that verifies receipts on a pull request (packages/receipts/docs/github-action.md)
packages/receipts/    the receipts package: src, test, examples, scripts, docs
packages/python/      the Python client package: agent_custody, tests run with uv against a real sidecar
packages/state/       the state package: src, test, examples
site/                 the website, generated from this repository's markdown by VitePress

Plan

The receipts package's roadmap is in its README. The state package has the ledger on JSONL, SQLite, or Postgres with every query answered from an index, the memory server behind the gateway and shared over HTTP, quarantine with three provenance levels and value-level evidence, policy over the fact being changed, consumed facts and blast radius, certified forget with keyed digests and verified removal from stores, retention sweeps and legal holds, the custody pack for counsel, a ledger that lives in a JSONL file, SQLite, or your Postgres, write-through to Mem0 and Zep, and the eval CLI with signed reports; its remaining item is the hosted plane, tracked as an issue in its README.