npm package: @proof-holdings/mcp-server
Description: MCP server for the proof.holdings API — 118 tools for identity verification, proofs, and asset management
Author: proof.holdings
Latest version: 1.0.0

# @proof-holdings/mcp-server

MCP (Model Context Protocol) server for the [proof.holdings](https://proof.holdings) API. Exposes 118 tools for AI agents to create verifications, validate proofs, manage assets, and more.

## Installation

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

Or run directly with npx (no install needed):

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

Or run with Docker:

```bash
docker run -i --rm -e PROOF_API_KEY=pk_live_xxx ghcr.io/proofholdings/mcp-server
```

## Configuration

| Variable | Required | Default | Description |
|---|---|---|---|
| `PROOF_API_KEY` | Yes | — | API key (`pk_live_...` or `pk_test_...`) |
| `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` |

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

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

### Docker

Use Docker if you prefer not to install Node.js:

```json
{
  "mcpServers": {
    "proof-holdings": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PROOF_API_KEY=pk_live_your_key_here",
        "ghcr.io/proofholdings/mcp-server"
      ]
    }
  }
}
```

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

## Tools (118)

### Verifications (12)

| Tool | Description |
|---|---|
| `create_verification` | Create a new verification |
| `get_verification` | Get a verification by ID |
| `list_verifications` | List verifications with optional filters |
| `trigger_verification` | Trigger a DNS/HTTP verification check |
| `submit_verification_code` | Submit an OTP/challenge code |
| `resend_verification` | Resend a verification (email channel) |
| `test_verify` | Auto-complete a verification (test mode only) |
| `list_verified_users` | List verified users grouped by external user ID |
| `get_verified_user` | Get a verified user's verifications |
| `start_domain_verification` | Start a B2B domain verification |
| `check_domain_verification` | Check a pending domain verification |
| `wait_for_verification` | Poll until verification reaches terminal state |

### Verification Requests (6)

| Tool | Description |
|---|---|
| `create_verification_request` | Create a multi-asset verification request |
| `get_verification_request` | Get a verification request by ID |
| `list_verification_requests` | List verification requests |
| `get_request_by_reference` | Get a verification request by reference ID |
| `cancel_verification_request` | Cancel a pending verification request |
| `wait_for_request` | Poll until request reaches terminal state |

### Proofs (4)

| Tool | Description |
|---|---|
| `validate_proof` | Validate a proof token (checks revocation) |
| `get_proof_status` | Get proof status by verification ID |
| `revoke_proof` | Revoke a proof by verification ID |
| `list_revoked_proofs` | Get the revocation list |

### Sessions (3)

| Tool | Description |
|---|---|
| `create_session` | Create a phone verification session |
| `get_session` | Get session status by ID |
| `wait_for_session` | Poll until session reaches terminal state |

### Assets (3)

| Tool | Description |
|---|---|
| `list_assets` | List verified assets |
| `get_asset` | Get an asset by ID |
| `revoke_asset` | Revoke a verified asset |

### Auth (3)

| Tool | Description |
|---|---|
| `get_current_user` | Get the current authenticated user |
| `list_auth_sessions` | List active auth sessions |
| `revoke_auth_session` | Revoke an auth session |

### Settings (4)

| Tool | Description |
|---|---|
| `get_usage` | Get API usage stats |
| `get_settings` | Get account settings |
| `update_settings` | Update account settings |
| `export_data` | Export account data |

### Templates (7)

| Tool | Description |
|---|---|
| `list_templates` | List message templates |
| `get_default_templates` | Get default templates |
| `get_template` | Get a template by channel and type |
| `update_template` | Update a template |
| `delete_template` | Delete a custom template |
| `preview_template` | Preview a rendered template |
| `render_template` | Render a template with variables |

### Webhook Deliveries (4)

| Tool | Description |
|---|---|
| `get_webhook_stats` | Get webhook delivery stats |
| `list_webhook_deliveries` | List webhook deliveries |
| `get_webhook_delivery` | Get a webhook delivery by ID |
| `retry_webhook_delivery` | Retry a failed webhook delivery |

### Billing (1)

| Tool | Description |
|---|---|
| `get_subscription` | Get subscription details |

### Projects (9)

| Tool | Description |
|---|---|
| `list_projects` | List projects |
| `create_project` | Create a project |
| `get_project` | Get a project by ID |
| `update_project` | Update a project |
| `delete_project` | Delete a project |
| `list_project_templates` | List project templates |
| `update_project_template` | Update a project template |
| `delete_project_template` | Delete a project template |
| `preview_project_template` | Preview a project template |

### Profiles (10)

| Tool | Description |
|---|---|
| `list_profiles` | List profiles |
| `create_profile` | Create a profile |
| `get_profile` | Get a profile by ID |
| `update_profile` | Update a profile |
| `delete_profile` | Delete a profile |
| `set_primary_profile` | Set a profile as primary |
| `update_profile_proofs` | Update profile proofs |
| `get_my_profile` | Get your public profile |
| `update_my_profile` | Update your public profile |
| `get_profile_assets` | Get profile assets |

### Emails (7)

| Tool | Description |
|---|---|
| `list_emails` | List email addresses |
| `remove_email` | Remove an email address |
| `set_primary_email` | Set an email as primary |
| `start_add_email` | Start adding a new email |
| `get_add_email_status` | Get email addition status |
| `verify_email_otp` | Verify email OTP code |
| `resend_email_otp` | Resend email OTP code |

### Phones (5)

| Tool | Description |
|---|---|
| `list_phones` | List phone numbers |
| `remove_phone` | Remove a phone number |
| `set_primary_phone` | Set a phone as primary |
| `start_add_phone` | Start adding a new phone |
| `get_add_phone_status` | Get phone addition status |

### API Keys (4)

| Tool | Description |
|---|---|
| `list_api_keys` | List API keys |
| `create_api_key` | Create an API key (2FA required) |
| `revoke_api_key` | Revoke an API key (2FA required) |
| `regenerate_api_key` | Regenerate an API key (2FA required) |

### 2FA (4)

| Tool | Description |
|---|---|
| `start_2fa` | Start a 2FA challenge |
| `get_2fa_status` | Get 2FA session status |
| `verify_2fa` | Verify a 2FA code |
| `verify_2fa_magic_link` | Verify via 2FA magic link |

### Domains (17)

| Tool | Description |
|---|---|
| `list_domains` | List domains |
| `add_domain` | Add a domain |
| `get_domain` | Get a domain by ID |
| `delete_domain` | Delete a domain |
| `verify_domain` | Verify a domain (DNS check) |
| `connect_cloudflare` | Connect domain via Cloudflare |
| `connect_godaddy` | Connect domain via GoDaddy |
| `connect_dns_provider` | Connect domain via DNS provider |
| `add_verification_provider` | Add a verification provider to a domain |
| `get_dns_providers` | Get available DNS providers |
| `verify_domain_with_credentials` | Verify domain with stored credentials |
| `check_domain_credentials` | Check domain credential status |
| `start_domain_email_verification` | Start domain email verification |
| `confirm_domain_email_code` | Confirm domain email verification code |
| `resend_domain_email` | Resend domain verification email |
| `setup_domain_email` | Set up domain email forwarding |
| `check_domain_email_status` | Check domain email setup status |

### DNS Credentials (3)

| Tool | Description |
|---|---|
| `list_dns_credentials` | List stored DNS credentials |
| `create_dns_credential` | Store DNS provider credentials |
| `delete_dns_credential` | Delete stored DNS credentials |

### User Requests (7)

| Tool | Description |
|---|---|
| `list_my_requests` | List your verification requests |
| `list_incoming_requests` | List incoming verification requests |
| `create_user_request` | Create a verification request |
| `claim_request_assets` | Claim assets from a completed request |
| `cancel_user_request` | Cancel a verification request |
| `extend_request` | Extend a request expiration |
| `share_request_email` | Share a request via email |

### User Domain Verify (3)

| Tool | Description |
|---|---|
| `start_user_domain_verification` | Start a user domain verification |
| `get_user_domain_verification_status` | Get domain verification status |
| `check_user_domain_verification` | Check domain verification result |

### Public Profiles (2)

| Tool | Description |
|---|---|
| `claim_username` | Claim a public profile username |
| `update_public_proofs` | Update public proof display |

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

Stdio only. The server communicates over stdin/stdout using the MCP protocol.

## Requirements

- Node.js >= 18.0.0
- A proof.holdings API key

## Links

- [proof.holdings](https://proof.holdings) — Product website
- [API Documentation](https://proof.holdings/docs/api) — REST API reference
- [Dashboard](https://proof.holdings/dashboard) — Manage your account and API keys

## License

[MIT](LICENSE)