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": "[email protected]" },
  "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

1. Independent verifiability — Every receipt verifiable offline with just the public key
2. Hash-then-disclose — Content hashed by default; plaintext opt-in
3. Transparent proxying — Drop-in layer; zero agent code changes
4. Append-only audit — No edits, deletions, or reordering
5. 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

• [x] Phase 0 — Specification & test vectors
• [x] Phase 1 — MCP proxy core
• [x] Phase 2 — SQLite index & query CLI
• [x] Phase 3 — Local web viewer
• [x] 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