mcp-server

# @proof-holdings/mcp-server

MCP (Model Context Protocol) server for the [proof.holdings](https://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:

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

Or as a config fragment:

```json
{ "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:

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

Or run directly with npx (no install needed):

```bash
npx @proof-holdings/mcp-server
```

## Configuration

| Variable | Required | Default | Description |
|---|---|---|---|
| `PROOF_API_KEY` | No | — | API key (`pk_live_...` or `pk_test_...`). Without it the server still starts in **public mode**: the keyless tools (account bootstrap, login, proof and delegation verification) work, and every other tool answers `api_key_required`. |
| `PROOF_BASE_URL` | No | `https://api.proof.holdings` | API base URL |

Get your API key from the [proof.holdings dashboard](https://proof.holdings/dashboard/api-keys).

## Client Setup

Add the following to your MCP client config file:

```json
{
  "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:

| Client | Config file |
|---|---|
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor | `.cursor/mcp.json` in your project root |
| Claude Code | Run `claude mcp add proof-holdings -- npx -y @proof-holdings/mcp-server` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |

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)

| Tool | Description |
|---|---|
| `create_verification` | Create a verification challenge |
| `get_verification` | Get verification status |
| `submit_verification_code` | Submit a verification code |
| `trigger_verification` | Trigger a verification check |
| `wait_for_verification` | Poll until it completes |
| `create_multi_channel_verification` | One phone, up to three channels, first completion wins |
| `create_verification_request` | Create a multi-asset request |
| `get_request_by_reference` | Look a request up by reference id |

### Domains & DNS (23 tools)

| Tool | Description |
|---|---|
| `add_domain` | Add a domain to verify |
| `verify_domain` | Check the challenge record and mint the proof |
| `connect_cloudflare` | Connect Cloudflare so records are written for you |
| `verify_domain_with_credentials` | Prove control using stored credentials |
| `setup_domain_email` | Set up sending from the domain |

### Account, settings & billing (37 tools)

| Tool | Description |
|---|---|
| `get_platform_summary` | One-call snapshot of the account |
| `get_usage` | Quota and usage for the period |
| `search` | Search across the account |
| `create_account` | Bootstrap a new account (no key needed) |
| `create_api_key` | Create a scoped API key |
| `list_assets` | List verified assets and their proof handles |

### HITL approvals & consent (22 tools)

| Tool | Description |
|---|---|
| `create_hitl` | Create a human-approval configuration |
| `create_confirmation` | Send an approval request to a person |
| `wait_for_confirmation` | Poll until a person approves or denies |
| `create_authorization` | Ask a person to consent to being contacted |
| `revoke_authorization` | Withdraw a consent |

### Circles & Proof of Me (20 tools)

| Tool | Description |
|---|---|
| `create_circle` | Create a circle of trusted contacts |
| `add_circle_member` | Add a contact |
| `invite_circle_member` | Send a single-use enrollment link |
| `create_identity_challenge` | Run a cross-channel identity check |

### Public profiles (16 tools)

| Tool | Description |
|---|---|
| `create_profile` | Create a public profile |
| `claim_username` | Claim a public username |
| `update_public_proofs` | Choose which proofs a profile shows |

### Templates & webhooks (11 tools)

| Tool | Description |
|---|---|
| `list_templates` | List message templates |
| `render_template` | Render a template with variables |
| `list_webhook_deliveries` | List webhook deliveries |
| `retry_webhook_delivery` | Retry a failed delivery |

### Delegations & proofs (10 tools)

| Tool | Description |
|---|---|
| `create_delegation` | Authorize an artifact from a domain you have proven |
| `revoke_delegation` | Revoke a delegation |
| `verify_delegation` | Check whether an artifact is authorized by the domain it claims |
| `validate_proof` | Verify a signed proof token (no key needed) |
| `get_proof_status` | Read a proof's status by its public handle |
| `list_revoked_proofs` | Read the revocation list (no key needed) |

### Sign-in & sessions (9 tools)

| Tool | Description |
|---|---|
| `start_login` | Begin a sign-in (no key needed) |
| `wait_for_login` | Poll until sign-in completes |
| `get_current_user` | Who the current session belongs to |
| `render_auth_link` | Render a sign-in link for the user to open |

## 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](https://proof.holdings/dashboard/api-keys).

## 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`:

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

The token is an ES256 JWT minted by [proof.holdings](https://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](https://proof.holdings/docs/api#delegations).

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`:

```bash
npm run delegation:publish -- --target mcp --token <jwt>
#