@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

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)

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