@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

start_add_phone

Begins a user-initiated reverse-OTP session to add a phone number via Telegram, WhatsApp, or SMS, returning a session ID plus channel-specific instructions, links, QR codes, or SMS details.

Instructions

Start adding a new phone number by reverse OTP: the user starts the exchange themselves and nothing is sent before they do; the response's instructions field says what they do (on telegram the bot then asks them to tap a button that shares their number). Returns a session ID; on telegram/whatsapp also deep_link, qr_code (base64 PNG) and qr_text (UTF-8 text QR), and on sms sms_message and sms_dids (one entry per region; a region with no number configured has an empty did) with no deep_link.

Agent usage: on telegram/whatsapp pass deep_link to render_auth_link for the link and a QR code. On sms there is no deep_link — show sms_message and a number from an sms_dids entry whose did is non-empty. Never hand a qr_text to a link renderer — it is a link already rendered as QR art. Then poll get_add_phone_status with the session ID.

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, or sign in with start_login — a session opens this tool — then call this tool again.

Input Schema

Name	Required	Description	Default
`channel`	Yes	Channel for phone verification

Output Schema

Name	Required	Description
`status`	Yes
`channel`	Yes
`qr_code`	No	Base64-encoded PNG QR code for `deep_link`
`qr_text`	No	UTF-8 text QR for `deep_link`, for terminal/agent rendering
`sms_code`	No	The short code the person texts (`sms` only)
`sms_dids`	No	Our SMS numbers, one entry per region and always all three. A region with no number configured carries an empty `did` and no QR code.
`deep_link`	No	Opens Telegram or WhatsApp with what the person sends (`telegram`, `whatsapp`)
`expires_at`	Yes
`session_id`	Yes
`sms_message`	No	The message to send (`sms` only)
`instructions`	Yes	One line telling the person what to do

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.7.2Nov 6, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "description": "A phone-add session: the person proves the number by sending from it over `channel`",
+  "properties": {
+    "channel": {
+      "type": "string"
+    },
+    "deep_link": {
+      "description": "Opens Telegram or WhatsApp with what the person sends (`telegram`, `whatsapp`)",
+      "type": "string"
+    },
+    "expires_at": {
+      "type": "string"
+    },
+    "instructions": {
+      "description": "One line telling the person what to do",
+      "type": "string"
+    },
+    "qr_code": {
+      "description": "Base64-encoded PNG QR code for `deep_link`",
+      "type": "string"
+    },
+    "qr_text": {
+      "description": "UTF-8 text QR for `deep_link`, for terminal/agent rendering",
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "sms_code": {
+      "description": "The short code the person texts (`sms` only)",
+      "type": "string"
+    },
+    "sms_dids": {
+      "additionalProperties": {},
+      "description": "Our SMS numbers, one entry per region and always all three. A region with no number configured carries an empty `did` and no QR code.",
+      "properties": {
+        "americas": {
+          "additionalProperties": {},
+          "properties": {
+            "did": {
+              "type": "string"
+            },
+            "flag": {
+              "type": "string"
+            },
+            "label": {
+              "type": "string"
+            },
+            "qr_code": {
+              "type": "string"
+            },
+            "qr_text": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "did",
+            "label",
+            "flag"
+          ],
+          "type": "object"
+        },
+        "europe": {
+          "additionalProperties": {},
+          "properties": {
+            "did": {
+              "type": "string"
+            },
+            "flag": {
+              "type": "string"
+            },
+            "label": {
+              "type": "string"
+            },
+            "qr_code": {
+              "type": "string"
+            },
+            "qr_text": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "did",
+            "label",
+            "flag"
+          ],
+          "type": "object"
+        },
+        "israel": {
+          "additionalProperties": {},
+          "properties": {
+            "did": {
+              "type": "string"
+            },
+            "flag": {
+              "type": "string"
+            },
+            "label": {
+              "type": "string"
+            },
+            "qr_code": {
+              "type": "string"
+            },
+            "qr_text": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "did",
+            "label",
+            "flag"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "americas",
+        "europe",
+        "israel"
+      ],
+      "type": "object"
+    },
+    "sms_message": {
+      "description": "The message to send (`sms` only)",
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "session_id",
+    "channel",
+    "status",
+    "expires_at",
+    "instructions"
+  ],
+  "type": "object"
+}

First observedv1.1.0Sep 9, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only declare non-read-only, non-destructive, which the description is consistent with. Beyond that it discloses the genuinely non-obvious behaviors: nothing is sent to the user before they act, results differ per channel (deep_link absent on sms), and clients fold tool output away so the agent must re-state the link/SMS text in its 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-loaded with the core mechanic, then returns, then agent usage, then the visibility caveat — a sensible ordering. Slight redundancy remains: "the user starts the exchange themselves and nothing is sent before they do" restates "reverse OTP", and "with no deep_link" is repeated in the agent-usage paragraph.

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?

Covers the full loop an agent needs: what initiates the exchange, how to present credentials per channel, what to do afterwards, and the authentication prerequisite. Return fields are described even though an output schema exists, which is a surplus rather than a gap.

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

Parameters5/5

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

Only one parameter, and the schema already documents the channel enum, so the baseline is high. The description still earns credit by explaining what choosing each channel actually produces downstream (deep_link/QR vs sms_message plus regional DIDs), which is meaning the schema cannot carry.

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

Purpose5/5

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

States a specific verb+resource+mechanism: "Start adding a new phone number by reverse OTP." It is clearly distinguishable from list_phones, remove_phone and the follow-up get_add_phone_status, and names the downstream sibling render_auth_link it feeds.

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

Usage Guidelines5/5

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

Gives an explicit per-channel playbook: pass deep_link to render_auth_link on telegram/whatsapp, show sms_message plus a non-empty sms_dids `did` on sms, then poll get_add_phone_status with the session ID. It also includes a negative instruction (never hand qr_text to a link renderer) and states the access prerequisite and two ways to satisfy it.

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

Deploy Server