@proof-holdings/mcp-server

MCP (Model Context Protocol) server for the proof.holdings API. Exposes 176 tools for AI agents to create verifications, validate proofs, manage assets, and more.

Two ways to connect

Hosted — nothing to install. The same tools are served over HTTP, and the client authenticates in the browser when a tool first needs an account:

claude mcp add --transport http proof https://api.proof.holdings/mcp

Or as a config fragment:

{ "mcpServers": { "proof": { "type": "http", "url": "https://api.proof.holdings/mcp" } } }

⚠️ Versions before 1.1.0 predate the delegation tools and the keyless public mode and expose an older, smaller surface than this README describes. If a client is pinned to 1.0.0, upgrade it or use the hosted server above. GET /api/v1/mcp/connect always serves the current instructions.

Local — this package. Installs and runs as a stdio server:

npm install -g @proof-holdings/mcp-server

Or run directly with npx (no install needed):

npx @proof-holdings/mcp-server

Configuration

Get your API key from the proof.holdings dashboard.

Client Setup

Add the following to your MCP client config file:

{
  "mcpServers": {
    "proof-holdings": {
      "command": "npx",
      "args": ["-y", "@proof-holdings/mcp-server"],
      "env": {
        "PROOF_API_KEY": "pk_live_your_key_here"
      }
    }
  }
}

Config file location by client:

If installed globally (npm install -g @proof-holdings/mcp-server), use "command": "proof-mcp" and remove the "args" field.

Tools (176 tools)

Group totals are exact. The tables name the tools you are most likely to reach for rather than all of them — your MCP client's own tools/list is the complete, current list, and it is the one this server answers from.

Verifications & requests (28 tools)

Domains & DNS (23 tools)

Account, settings & billing (37 tools)

HITL approvals & consent (22 tools)

Circles & Proof of Me (20 tools)

Public profiles (16 tools)

Templates & webhooks (11 tools)

Delegations & proofs (10 tools)

Sign-in & sessions (9 tools)

Test Mode

Use a test-mode API key (pk_test_*) to interact with the API without creating real verifications. Test-mode keys are available in your dashboard.

Transport

Two transports ship in this package:

• stdio (default, mcp-server / proof-mcp) — the server communicates over stdin/stdout. One user per process; this is what a client launches locally.
• Streamable HTTP (node dist/remote.js) — a remote server that many users connect to over the network by URL, with no install. A connection starts ANONYMOUS — the keyless surface (account bootstrap, login, proof and delegation verification) works with no credential at all — and a tool that needs an account answers 401 with a WWW-Authenticate challenge naming the authorization server, which is what a standards-compliant client follows to sign in. The 401 lands on the TOOL CALL and never on a bare initialize or tools/list FOR AN ANONYMOUS CONNECTION: measured against live clients, refusing an anonymous handshake reads to the user as a connection timeout rather than as an invitation to log in. Three shapes are refused at the handshake instead — a presented token that does not resolve (there the 401 is what makes a client refresh), a request whose credential does not match the session it names, and an opening batch that smuggles a keyed tool call alongside initialize. A signed-in client sends the API key it was granted in the Authorization header — the only place a credential is read, never a query parameter — and each connection gets its own server and HTTP client, so one user's key or session can never reach another. PORT (default 3100), MCP_MAX_SESSIONS (default 100), MCP_SESSION_TTL_MS (default 30 min, counted from the last POST the server ACCEPTED — one it answered below 400. A POST refused before any work happens does not postpone it, whether the refusal is ours (body over 4MB) or the transport's (unparseable or empty body, unsupported mcp-protocol-version, a second initialize); and an open event stream is a connection, not activity, so a session whose only traffic is that stream ages out. The official client does not recover from this on its own: measured against SDK 1.27.1, the stream's reconnect gives up after two attempts and the next tool call fails with unknown_session until the host reconnects the server. Size the TTL with that in mind — it is a memory bound paid for in reconnects, not a transparent one); /healthz reports the live session count.

Delegation (_meta)

The server card (server.json) can carry a Proof of Delegation publication under the namespaced _meta key holdings.proof/delegation:

{
  "_meta": {
    "holdings.proof/delegation": { "token": "<delegation JWT>" }
  }
}

The token is an ES256 JWT minted by proof.holdings attesting exactly one thing: the controller of the principal domain authorized the delegate artifact for the listed scopes. It is not a statement that the server is safe, audited, or endorsed. A verifier checks the signature against the issuer JWKS, then compares principal and delegate to facts it resolved itself — a token copied into another package fails that comparison, because its delegate names the genuine artifact. Details: Delegations — API reference.

When the card is published through the official MCP registry, the same entry is nested under _meta["io.modelcontextprotocol.registry/publisher-provided"] — readers should check both locations.

Maintainers: the entry is written by the fail-closed publish tool, never by hand — from the repository root, after the delegation is minted for pkg:npm/@proof-holdings/mcp-server: