Audit Ledger MCP

audit-ledger-mcp

Connect Claude, Cursor, LangGraph, or your own agent to the [AI Audit Ledger](https://github.com/shahidh68/audit-ledger). This MCP server gives an agent the tools to record, check, and list decisions in a tamper-evident log with one line of config.

It is built for teams that need a clear record of AI decisions: EU AI Act Article 12 logging, FCA SS1/23 model risk evidence, and GDPR data minimisation. Raw personal data is hashed locally before anything is sent, so the ledger only sees fingerprints.

The AI Audit Ledger family. This MCP server writes decisions to the

ledger, which proves what happened

and whether the record was changed. The

AI Decision Evidence Hub sits

above the ledger, read-only. It turns each lightweight decision record into an

audit case file by showing what evidence is present, what is still missing, who

owns each gap, and the current readiness score. Family:

audit-ledger · audit-ledger-mcp ·

evidence-hub.

[Try the live dashboard →](https://d2pfirb2397ixy.cloudfront.net/?demo=1) · 30 synthetic decisions written via this MCP server, queryable and verifiable.

A LangGraph workflow calls record_decision after each agent step. Three audit events written to the live ledger; every one independently verifiable.

---

What it does

Exposes four tools to any MCP-compatible agent:

Each call ends up as a regulator-grade audit record in your deployed ledger — DynamoDB for query, S3 Object Lock COMPLIANCE mode for the immutable copy, 7-year retention by default.

---

Quick start — zero configuration

npx -y audit-ledger-mcp

That's it. With no environment variables, the server boots into sandbox mode and writes records to a shared public tenant on a hosted ledger. You can try every tool — record_decision, verify_decision, verify_completeness, list_decisions — without provisioning anything.

When sandbox mode is active, you'll see a banner on stderr:

[audit-ledger-mcp] ─────────────── SANDBOX MODE ───────────────

[audit-ledger-mcp] No AUDIT_API_URL configured. [audit-ledger-mcp] Using the public sandbox at sandbox-public. [audit-ledger-mcp] View: https://d2pfirb2397ixy.cloudfront.net [audit-ledger-mcp] Do NOT write real personal data...

Sandbox properties

Wire it into Claude Desktop with zero config

{

"mcpServers": { "audit-ledger-sandbox": { "command": "npx", "args": ["-y", "audit-ledger-mcp"] } } }

Restart Claude Desktop. The four tools appear in the MCP menu immediately. Try asking Claude to "record this decision: should X be approved?" and watch a record land in the sandbox dashboard.

---

Production install

For real workloads, deploy your own audit ledger and point the MCP server at it:

npm install -g audit-ledger-mcp

Configure with the API URL plus your tenant keys (any of them being set switches off sandbox mode). AUDIT_HMAC_KEY is technically optional for backwards compatibility but strongly recommended — see the note above the value below:

export AUDIT_API_URL="https://<api-id>.execute-api.<region>.amazonaws.com/prod"

export AUDIT_WRITE_KEY=" " export AUDIT_READ_KEY=" "

Strongly recommended. Tenant-held secret used to HMAC PII and prompts

locally before sending. Generate once, store next to AUDIT_WRITE_KEY:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

If unset, the MCP falls back to plain SHA-256 and warns once (back-compat).

export AUDIT_HMAC_KEY=" "

Optional

export AUDIT_TIMEOUT_MS=5000 # default 5000 export AUDIT_RETRY_ATTEMPTS=3 # default 3

The full template lives in .env.example.

---

Wire it into an agent

Claude Desktop

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

{

"mcpServers": { "audit-ledger": { "command": "npx", "args": ["-y", "audit-ledger-mcp"], "env": { "AUDIT_API_URL": "https:// .execute-api. .amazonaws.com/prod", "AUDIT_WRITE_KEY": " ", "AUDIT_READ_KEY": " ", "AUDIT_HMAC_KEY": " " } } } }

AUDIT_HMAC_KEY is the tenant secret used to keyed-hash PII locally before any payload leaves the MCP server process. Generate it once with node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" and store the result in the env block above. The MCP never transmits this value, only reads it.

Restart Claude Desktop. You'll see "audit-ledger" in the MCP tools menu. Ask Claude something like *"Record this decision: I declined the application because…"* and watch it call record_decision automatically.

Cursor

In Cursor settings → MCP → add server:

{

"mcpServers": { "audit-ledger": { "command": "npx", "args": ["-y", "audit-ledger-mcp"], "env": { "AUDIT_API_URL": "https:// .execute-api. .amazonaws.com/prod", "AUDIT_WRITE_KEY": " ", "AUDIT_READ_KEY": " ", "AUDIT_HMAC_KEY": " " } } } }

LangGraph (Python)

Using langchain-mcp-adapters:

from langchain_mcp_adapters.client import MultiServerMCPClient

from langgraph.prebuilt import create_react_agent from langchain_anthropic import ChatAnthropic import os

client = MultiServerMCPClient({ "audit-ledger": { "command": "npx", "args": ["-y", "audit-ledger-mcp"], "transport": "stdio", "env": { "AUDIT_API_URL": os.environ["AUDIT_API_URL"], "AUDIT_WRITE_KEY": os.environ["AUDIT_WRITE_KEY"], "AUDIT_READ_KEY": os.environ["AUDIT_READ_KEY"], "AUDIT_HMAC_KEY": os.environ["AUDIT_HMAC_KEY"], }, } })

tools = await client.get_tools() agent = create_react_agent( ChatAnthropic(model="claude-sonnet-4-7-20251022"), tools, )

The agent can now call record_decision, verify_decision, verify_completeness, list_decisions

result = await agent.ainvoke({ "messages": [{"role": "user", "content": "Triage this loan application…"}] })

Custom client (raw MCP)

AUDIT_API_URL=... AUDIT_WRITE_KEY=... AUDIT_READ_KEY=... AUDIT_HMAC_KEY=... npx -y audit-ledger-mcp

The server speaks MCP over stdio. Send initialize, tools/list, and tools/call requests per the MCP specification.

---

How a record_decision call flows

Agent                  audit-ledger-mcp                  AWS (your ledger)

Storage on the AWS side happens asynchronously through SQS → Processor Lambda → DynamoDB + S3 Object Lock. See the main repo's ARCHITECTURE.md for the full path.

---

Tool reference

record_decision

Record an AI decision to the ledger.

verify_decision

Tamper-check a stored record.

Returns the DynamoDB record, the S3 record, and integrity_verified: true/false.

verify_completeness

Detect missing records. Sister tool to verify_decision: that one proves a record that exists has not been altered; this one proves no records have been deleted.

Returns the requested range, the expected vs found count, the list of missing sequence numbers, and a human-readable note.

{

"tenant_id": "acme-prod", "range": { "from": 1, "to": 142 }, "expected_count": 142, "found_count": 140, "missing": [47, 91], "note": "Found 2 missing sequence number(s) in range. Each gap represents a deleted, lost, or never-written record. Cross-check against burned_sequence log entries before treating as a deletion." }

list_decisions

List recent decisions for the calling tenant.

---