@ledgerproof/mcp-server

A Model Context Protocol server that lets any MCP client (Claude Desktop, Claude Code, IDEs, agents) issue and verify EU AI Act Article 50 transparency receipts through @ledgerproof/sdk.

LedgerProof implements the IETF SCITT architecture drafts (draft-ietf-scitt-architecture-22) with COSE Receipts (draft-ietf-cose-merkle-tree-proofs-18), and additionally anchors a daily Merkle root to Bitcoin (OP_RETURN). It is an early implementation of live IETF Internet-Drafts — not an RFC, not a standard, not certified, not "SCITT compliant." That precision is deliberate; please keep it in any derived copy.

Issuing a receipt is a real, deliberate action: each receipt's daily Merkle root is anchored to Bitcoin, which costs a Bitcoin transaction fee. Do not wire agents to auto-issue on loose triggers. The bundled ledgerproof_when_to_issue prompt spells out when issuance is (and isn't) appropriate.

Transports

This server speaks the two current MCP transports. The deprecated HTTP+SSE transport is intentionally not used.

• stdio (default) — for local clients that launch the server as a subprocess.
• Streamable HTTP (StreamableHTTPServerTransport) — for networked clients. In this mode ledgerproof_issue_receipt requires precomputed_sha256 and rejects raw payloads, so artifact bytes never cross the network.

Tools

| Tool | Purpose | |---|---| | ledgerproof_issue_receipt | Produce an Article-50 record for AI-generated content and register it. Exactly one of artifact or precomputed_sha256, plus aiSystemId, deployerName, contentCategory, etc. Mirrors publishAiArticle50. Returns {sequence, entry_hash, verify_url, anchor_status:"pending"}. | | ledgerproof_verify_receipt | Verify by {sequence} (API lookup) or {transparent_statement} (SCITT bundle, trust-minimized §7 check → {issuerSignatureValid, inclusionProofValid, receiptSignatureValid, bitcoinConfirmed, valid}). | | ledgerproof_check_anchor | Poll a {sequence} for Bitcoin anchor status (pending → anchored with txid, block, Merkle proof). | | ledgerproof_hash_artifact | SHA-256 a {payload} locally so raw content never leaves the machine. |

Prompt

• ledgerproof_when_to_issue — scoped guidance: issue only when deliberately "producing an Article-50 transparency record for AI-generated content," and a reminder that anchoring costs a Bitcoin tx fee, so do not auto-fire on loose triggers.

Honest behavior notes / gaps

• Anchoring is asynchronous. Issuance always returns anchor_status: "pending". The server never reports a fabricated "anchored" status — ledgerproof_check_anchor reports anchored only when the API returns a real Bitcoin txid. Poll until then.
• Raw payloads stay local even on stdio. The SDK hashes the artifact locally and only the artifact_hash (never the bytes) is sent to the LedgerProof API. Streamable HTTP additionally keeps the bytes off the MCP hop by requiring precomputed_sha256.
• SCITT verification is guarded. verifyTransparentStatement lives in the SDK's scitt/ module, which is being built in parallel and may not be exported yet. If it's absent, ledgerproof_verify_receipt (Transparent Statement mode) returns a clear "not available in the installed SDK" error instead of failing the build. Sequence-mode verification works today.
• precomputed_sha256 issuance depends on an SDK feature. The base publishAiArticle50 always hashes raw bytes and exposes no precomputed-hash entrypoint. The server passes the hash through optimistically (forward-compat); if the installed SDK can't accept it, the tool returns a precise error rather than registering a record with the wrong artifact_hash. Until the SDK adds a precomputed-hash publish path, issue from raw artifact over stdio.

Configuration (environment variables)

| Variable | Required | Default | Notes | |---|---|---|---| | LEDGERPROOF_PUBLISHER_ID | yes | — | Legal-entity id (LEI/EUID/VAT/DID). Not an email. | | LEDGERPROOF_DEPLOYER_COUNTRY | yes | — | ISO country code, e.g. DE. | | LEDGERPROOF_API_KEY | yes | — | LedgerProof API key. | | LEDGERPROOF_API_BASE | no | https://api-eu.ledgerproofhq.io | API base URL (api-eu.ledgerproofhq.io). | | LEDGERPROOF_SIGNING_KEY_HEX | no | ephemeral | Ed25519 signing seed (hex). Never logged. | | LEDGERPROOF_KEY_PATH | no | — | Path to a file containing the hex seed (alt to _HEX). | | LEDGERPROOF_KEY_ID | no | default | Key id registered with the service. |

HTTP-only (optional): PORT/LEDGERPROOF_MCP_PORT (default 3000), LEDGERPROOF_MCP_HOST (default 127.0.0.1), LEDGERPROOF_MCP_TRANSPORT=http (same as --http).

The Ed25519 signing key is never logged, never returned by any tool, and never serialized. Only its presence (provided vs ephemeral) is printed at boot.

Install / build

npm install
npm run build      # tsc → dist/
npm run lint       # tsc --noEmit

Run

# stdio (default)
npx @ledgerproof/mcp-server

# Streamable HTTP on http://127.0.0.1:3000/mcp
npx @ledgerproof/mcp-server --http --port 3000

MCP client config

stdio

{
  "mcpServers": {
    "ledgerproof": {
      "command": "npx",
      "args": ["-y", "@ledgerproof/mcp-server"],
      "env": {
        "LEDGERPROOF_PUBLISHER_ID": "LEI:5493001KJTIIGC8Y1R12",
        "LEDGERPROOF_DEPLOYER_COUNTRY": "DE",
        "LEDGERPROOF_API_KEY": "sk_live_...",
        "LEDGERPROOF_API_BASE": "https://api-eu.ledgerproofhq.io",
        "LEDGERPROOF_SIGNING_KEY_HEX": "<32-byte-hex-ed25519-seed>",
        "LEDGERPROOF_KEY_ID": "default"
      }
    }
  }
}

Streamable HTTP

Start the server (npx @ledgerproof/mcp-server --http --port 3000), then point the client at the URL:

{
  "mcpServers": {
    "ledgerproof": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Over Streamable HTTP, call ledgerproof_hash_artifact first and pass the result to ledgerproof_issue_receipt as precomputed_sha256 — raw payloads are rejected on this transport by design.

License

Apache-2.0