Package Exports

agent-receipts-cli

Readme

agent-receipts

Cryptographically-signed audit trails for AI agents via the Model Context Protocol.

Every tool call your AI agent makes — file writes, API calls, browser actions — gets a tamper-evident, Ed25519-signed receipt. Drop-in middleware. No agent code changes. Works with every MCP client.

Quick Start (2 minutes)

# Install
npm install -g agent-receipts

# Initialize keys and config
agent-receipts init

# Wrap any MCP server
agent-receipts wrap -- npx -y @modelcontextprotocol/server-filesystem /tmp

# View your receipts
agent-receipts log
agent-receipts ui --port 3000

What You Get

Every AI agent tool call produces a signed receipt like this:

{
  "v": "0.1",
  "id": "rcpt_01HQX7K9V3M2X8N5P0Q7R2T4W6",
  "ts": "2026-05-19T14:32:11.234Z",
  "agent": { "framework": "claude-code", "model": "claude-sonnet-4-20250514" },
  "principal": { "type": "user", "id": "aswin@agent-viscro.dev" },
  "action": {
    "kind": "tool_call",
    "tool": "filesystem.write_file",
    "inputs": { "disclosure": "hash", "hash": "sha256:a3f5e9..." },
    "outputs": { "disclosure": "hash", "hash": "sha256:7e8d9f..." },
    "duration_ms": 47
  },
  "sig": { "key_id": "key_2026_05", "alg": "ed25519", "value": "MEUCIQDk6..." }
}

Content is hashed by default — your data stays private. The signature proves the receipt hasn't been tampered with.

Integration Recipes

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y", "agent-receipts", "wrap", "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem",
        "/Users/you/Documents"
      ]
    }
  }
}

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y", "agent-receipts", "wrap", "--",
        "npx", "-y", "@modelcontextprotocol/server-github"
      ],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}

Cursor

Add to Cursor's MCP settings (Settings → MCP Servers):

{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y", "agent-receipts", "wrap", "--",
      "npx", "-y", "@modelcontextprotocol/server-filesystem",
      "/path/to/workspace"
    ]
  }
}

Windsurf / Cline / Any MCP Client

The pattern is always the same — prefix your existing MCP server command with npx -y agent-receipts wrap --:

npx -y agent-receipts wrap -- <your-existing-mcp-command> <args>

CLI Reference

Command	Description
`agent-receipts init`	Generate keys, create config
`agent-receipts wrap -- <cmd>`	Wrap an MCP server with receipt signing
`agent-receipts log`	Show recent receipts (filterable)
`agent-receipts log --tool "filesystem.*"`	Filter by tool (wildcard)
`agent-receipts log --chain <id>`	Show causal chain
`agent-receipts stats --by tool`	Statistics grouped by tool/principal/decision
`agent-receipts verify <file>`	Verify receipt signatures
`agent-receipts inspect <id>`	Inspect a single receipt
`agent-receipts ui`	Launch local web viewer
`agent-receipts reindex`	Rebuild SQLite index from JSONL
`agent-receipts export -o <path>`	Export portable receipt archive
`agent-receipts key list`	List signing keys
`agent-receipts key generate-signing`	Generate a new signing key

Design Principles

Independent verifiability — Every receipt verifiable offline with just the public key
Hash-then-disclose — Content hashed by default; plaintext opt-in
Transparent proxying — Drop-in layer; zero agent code changes
Append-only audit — No edits, deletions, or reordering
Cryptographic agility — Algorithm identifiers in every signature

How It Works

AI Agent (Claude, Cursor, etc.)
    │
    │ MCP protocol (stdio)
    ▼
agent-receipts proxy
    │  ├─ intercepts tool calls
    │  ├─ signs receipts (Ed25519)
    │  └─ stores to JSONL + SQLite
    ▼
Downstream MCP Server (filesystem, GitHub, etc.)

The proxy is transparent — your agent sees identical behavior whether the proxy is present or absent. Receipt signing is async and fire-and-forget — it never adds latency to tool calls or breaks your agent.

Storage

JSONL (source of truth) — append-only, greppable, recoverable
SQLite (query index) — fast filters, stats, chain traversal
Default location: ~/.agent-receipts/

Specification

The receipt format is formally specified in spec/v0.1/SPEC.md with 8 conformance test vectors and a Python reference implementation. Any conforming implementation produces byte-identical signatures from the same inputs.

Roadmap

Phase 0 — Specification & test vectors
Phase 1 — MCP proxy core
Phase 2 — SQLite index & query CLI
Phase 3 — Local web viewer
Phase 4 — Distribution & launch
Phase 5 — Multi-server daemon mode
Phase 6 — Transparency log & anchoring
Phase 7 — Policy DSL & enforcement
Phase 8 — Selective disclosure & privacy
Phase 9 — Enterprise hardening (HSM, SIEM)
Phase 10 — Standards track (IETF)

Contributing

See CONTRIBUTING.md for guidelines. Issues and PRs welcome.

Security

See SECURITY.md for our security policy and disclosure process.

License

Code: MIT · Specification: CC-BY-4.0

Built by Aswin Sasi · Agent Viscro

agent-receipts-cli