@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

create_verification

Initiates identity verification for a phone, email, domain, social handle, wallet, account, or Telegram bot via a chosen channel, returning the challenge needed to prove ownership.

Instructions

Create a new identity verification. Initiates a verification flow for an asset identifier (phone number, email, domain, social handle, wallet address, account, or Telegram bot).

Agent usage: pass the asset type, the delivery channel, and the identifier (e.g. type "phone", channel "sms", identifier "+37060000000"; or type "email", channel "email", identifier "user@example.com"). The response carries a challenge object with the instruction for the chosen channel — except a telegram_bot verification made with a LIVE key, which the server completes on the spot and answers with status: verified plus a proof token and no challenge at all; with a pk_test_ key that same call stays pending and does carry a challenge. On the messenger channels it also carries challenge.deep_link — pass THAT to render_auth_link to give the user a clickable link and a QR code. This endpoint returns no qr_text at all. For OTP-based flows (sms/email), the user receives a code — poll get_verification or use wait_for_verification to track completion. For Telegram/WhatsApp, the user clicks the deep link to verify.

The user does not see tool results — most clients fold them away, render_auth_link's output included. Before you wait or poll, put what the user must act on into your own reply text: the link itself (not a sentence announcing it), the SMS text and number, or a note to check their inbox.

ACCESS: needs a Proof account. Set PROOF_API_KEY and restart this server, then call this tool again. start_login does NOT open this tool.

Input Schema

Name	Required	Description
`type`	Yes	Asset type being verified
`channel`	Yes	Verification channel (must match the asset type, e.g. sms/whatsapp/telegram for phone)
`bot_token`	No	Telegram bot token (required for channel "telegram_bot_token")
`identifier`	Yes	The asset identifier to verify (E.164 phone, email address, domain, handle, wallet address, ...)
`profile_id`	No	The sub-account (24 hex characters) this is for; omitted, the key's own sub-account, else the primary. Its branding and templates are used for every message.
`dns_provider`	No	DNS provider credentials (required for channel "auto")
`email_prefix`	No	Mailbox prefix for domain email verification
`client_metadata`	No	Custom key-value metadata
`external_user_id`	No	Your application user ID for grouping verifications
`proof_expiry_days`	No	Per-request proof expiry override in days (1-365)

Output Schema

Name	Required	Description
`id`	No	MongoDB ObjectId
`type`	No	Type of asset being verified. Not yet available — no channel of theirs can be completed, so a create or start answers 400 `channel_not_available`: social, wallet, account.
`proof`	No	Proof token after successful verification
`status`	No	Current status of the verification
`channel`	No	Channel used for verification. Not yet available — a create or start naming one answers 400 `channel_not_available`: github, google, facebook, x, linkedin, instagram, youtube, tiktok, ethereum, solana, bitcoin, coinbase, kraken.
`attempts`	No
`challenge`	No	Challenge details for verification
`created_at`	No
`identifier`	No	The identifier being verified; absent for an identifier-free phone verification, whose number is learned only when the person completes it
`updated_at`	No
`verified_at`	No
`max_attempts`	No
`external_user_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.7.2Nov 6, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```
addedInput schema / properties / client_metadata / propertyNames
```
Added value: +{
+  "type": "string"
+}
```
addedInput schema / properties / dns_provider / propertyNames
```
Added value: +{
+  "type": "string"
+}
```

addedInput schema / properties / profile_id

Added value: +{
+  "description": "The sub-account (24 hex characters) this is for; omitted, the key's own sub-account, else the primary. Its branding and templates are used for every message.",
+  "pattern": "^[0-9a-fA-F]{24}$",
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "attempts": {},
+    "challenge": {
+      "description": "Challenge details for verification"
+    },
+    "channel": {
+      "description": "Channel used for verification. Not yet available — a create or start naming one answers 400 `channel_not_available`: github, google, facebook, x, linkedin, instagram, youtube, tiktok, ethereum, solana, bitcoin, coinbase, kraken."
+    },
+    "created_at": {},
+    "external_user_id": {},
+    "id": {
+      "description": "MongoDB ObjectId"
+    },
+    "identifier": {
+      "description": "The identifier being verified; absent for an identifier-free phone verification, whose number is learned only when the person completes it"
+    },
+    "max_attempts": {},
+    "proof": {
+      "description": "Proof token after successful verification"
+    },
+    "status": {
+      "description": "Current status of the verification"
+    },
+    "type": {
+      "description": "Type of asset being verified. Not yet available — no channel of theirs can be completed, so a create or start answers 400 `channel_not_available`: social, wallet, account."
+    },
+    "updated_at": {},
+    "verified_at": {}
+  },
+  "type": "object"
+}

First observedv1.1.0Sep 9, 2026

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well past the readOnly/destructive annotations: discloses that a telegram_bot call with a LIVE key completes immediately (status verified + proof token, no challenge) while pk_test_ stays pending, that no qr_text is returned, and that a PROOF_API_KEY must be set (start_login does not open it). Also warns that clients hide tool results, so the link/code must be surfaced in the agent's own reply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what it does and the invocation recipe, then the response variants, then the access caveat. Dense but nearly every sentence carries actionable information; the live-vs-test key explanation is slightly repetitive.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, multi-channel creation tool with an output schema, this covers the invocation recipe, the divergent response shapes, downstream polling alternatives, and the auth prerequisite. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description adds value by pairing concrete examples ('type "phone", channel "sms", identifier "+37060000000"') that convey the type/channel matching constraint better than the schema's generic 'must match the asset type' note. It does not touch the optional params (profile_id, proof_expiry_days, client_metadata), relying on schema docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a new identity verification') and enumerates the asset kinds it covers (phone, email, domain, social, wallet, account, Telegram bot). It never names the near-siblings create_verification_request or create_multi_channel_verification, so an agent must infer the boundary itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete routing: pass type/channel/identifier, then 'poll get_verification or use wait_for_verification' for OTP flows, and pass challenge.deep_link to render_auth_link. Lacks an explicit 'do not use this when...' exclusion against the many sibling verification tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server