Proof Holdings

@proof-holdings/mcp-server

MCP (Model Context Protocol) server for the proof.holdings API. Exposes 179 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 at https://api.proof.holdings/mcp. Any MCP client or agent framework with HTTP transport can connect — add the URL as a remote MCP server in its settings (the config key varies by client). Authentication happens in the browser the first time a tool needs an account. 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. The current instructions are always at https://proof.holdings/md/docs/mcp.md.

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, or let the server get one for you with login (below).

Sign in from a terminal

npx @proof-holdings/mcp-server login

1. Pick how to log in — Telegram, WhatsApp, SMS or email (--channel, or asked). The terminal shows the link and a QR code to scan with your phone, the text and number to send for SMS, or asks for the code from the email.
2. Creating an API key needs one more confirmation, preferably on a different channel; it also runs in the terminal.
3. The new key is saved in ~/.proof-holdings/credentials (readable by you only), under the API in PROOF_BASE_URL. The server uses it from its next start, so restart your MCP client's server.
4. The sign-in session the terminal used is then signed out. If that fails, login says so; sign it out in the dashboard under Settings → Security → Signed-in devices.

PROOF_API_KEY, when set, always wins over the saved key, and a key saved for one API (say, staging) is never sent to another. Then leave env out of the client config:

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

The key does not expire. Logging in again replaces the saved key but does not revoke the old one, and logout only forgets it locally: revoke keys you no longer use in the dashboard (API keys) or with the revoke_api_key tool. login needs an interactive terminal and an https:// API (plain http only for localhost).

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:

Keep the scoped npx -y @proof-holdings/mcp-server command even after a global install. A bare command name is looked up on PATH, or by npx in the npm registry, where it can belong to someone else's package.

Tools (179 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 (39 tools)

HITL approvals & consent (22 tools)

Circles & Proof of Me (15 tools)

Public profiles (12 tools)

Templates & webhooks (11 tools)

Webhook endpoints (7 tools)

Each endpoint has its own URL, events and signing secret, and serves either every sub-account or the ones you select. A signing secret is returned only on create and on rotate — store it then.

Delegations & proofs (13 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, what npx -y @proof-holdings/mcp-server starts) — 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. /mcp serves POST (every JSON-RPC message) and DELETE (ending a session); every other method — including the optional standalone GET event stream — answers 405 with Allow: POST, DELETE, whatever session or credential the request carries. Nothing on this server pushes notifications, so declining the stream costs a client nothing, and it is what lets a client on Node 26's built-in fetch work: over HTTP/2 to the edge, with that stream open, it never sent its next request. 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 neither does a refused meth