mcp-context-receipts

# MCP Provenance Capsules

Portable, privacy-first evidence for every MCP tool call.

MCP gives models access to powerful tools. Provenance Capsules answer the hard question that follows: what ran, exactly, and can anyone verify the record later?

This project is a tiny, dependency-free universal library (Node.js, Deno, Bun, Browser) and an MCP server that emits cryptographically linked evidence without storing raw prompts, arguments, or results.

Playground

You can try the library directly in your browser without any setup! Try the GitHub Pages Playground here!

Related MCP server: Agent Audit Logger MCP

Why this is not another audit log

• Privacy by default: only SHA-256 digests leave the call boundary; raw payloads stay in the caller.

• Tamper evident: each capsule carries an HMAC signature and the previous capsule hash.

• Portable: JSON capsules and JSONL streams work with object storage, SIEMs, test fixtures, or a database.

• MCP-native: use it as a stdio server with any compatible client, or import the core class into an existing server.

• Universal & Robust: Uses the native Web Crypto API so it works universally in browsers, Node 20+, Deno, and Edge Workers. Features a deterministic JSON stringifier to eliminate fragile signature failures due to key reordering.

• Verifiable later: anyone holding the capsule stream and verification secret can detect edits, deletion, and reordering.

• Small surface: Zero runtime dependencies, no hosted service required.

Quick start

Requires Node.js 20+ (for the MCP server).

npm start

Configure an MCP client with command node and argument /absolute/path/to/mcp-provenance-capsules/src/server.js. Set MCP_RECEIPT_SECRET outside source control.

The server exposes create_receipt and verify_receipt tools.

Embed it

Import ReceiptChain from src/receipts.js, construct it with your secret, and await chain.create(...). Because it uses the native Web Crypto API, all operations are asynchronous.

import { ReceiptChain } from "./src/receipts.js";

const chain = new ReceiptChain("your-secret");

// Create a receipt
const receipt = await chain.create({
  server: "demo",
  tool: "fetch_data",
  arguments: { id: 123 },
  result: { status: "ok" },
  durationMs: 42
});

// Verify a receipt
const verification = await chain.verify(receipt);
console.log(verification.valid); // true

Capsule anatomy

A capsule contains a version, sequence number, UTC timestamp, server and tool identity, argument and result hashes, duration, previous hash, HMAC signature, and its own hash. The canonical schema lives at schema/capsule.schema.json.

The chain is storage-agnostic: write JSONL to object storage, a database, or your existing audit pipeline. The library never persists data itself.

Verify a stream

Set the same secret used when creating capsules, then run MCP_RECEIPT_SECRET='your-secret' npx verify-capsule capsules.jsonl.

The command prints one machine-readable verification result per capsule and exits non-zero if any signature, hash, or chain link fails.

Security notes

Use a high-entropy secret from your deployment secret manager. Rotate secrets by starting a new chain and recording the rotation boundary in storage. HMAC proves integrity to parties that possess the secret; it is not a public, non-repudiable signature.

Product boundary

This project is not a hosted compliance platform, payload recorder, or replacement for authorization. It is the evidence layer underneath those systems.

Development

npm test

MIT licensed. Contributions are welcome, especially durable sinks, key rotation, OpenTelemetry export, and adapters for additional MCP transports—while preserving the no-raw-payload default.