@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

start_login

Initiates a login session by sending an authentication challenge through Telegram, WhatsApp, SMS, or email, then returns a session ID to poll until the user completes sign-in.

Instructions

Start a login session by sending an authentication challenge to the user's chosen channel (Telegram, WhatsApp, SMS, or email). Returns a session ID and, FOR TELEGRAM AND WHATSAPP ONLY, deep_link, qr_code (base64 PNG) and qr_text (UTF-8 text QR for terminal display); on sms it returns sms_message with sms_dids instead, and on email nothing to display.

Agent usage: (1) Call start_login with the desired channel and phone_number (for SMS) or email (for email). (2) Present the challenge, and WHICH FIELD depends on the channel. On telegram/whatsapp pass deep_link to render_auth_link, which returns the clickable link and a QR code to you; in a chat client the link is what the user acts on, since they are usually on the same machine. On sms deep_link is an EMPTY STRING and render_auth_link will reject it — show sms_message and let the user pick a number from sms_dids. suggested_region is always set, but the matching ENTRY in sms_dids may be missing (europe and israel appear only when a number is configured) or present with an empty did, so offer that region first only when sms_dids[suggested_region] exists and carries a number, and otherwise offer whatever the object does. On email there is nothing to display at all, and nothing to check either: a result means the mail was accepted for delivery, so tell the user to open their inbox. A delivery failure is an ERROR here, not a field — the tool answers challenge_delivery_failed and NO session exists, so do not call wait_for_login; retry, or offer another channel. Never hand qr_text to a link renderer — it is the link already rendered as QR art, so print it verbatim inside a fenced code block or not at all, because its rows stop scanning the moment one wraps or a blank line lands between them. (3) Once your reply shows the user the challenge, call wait_for_login with the returned session ID to poll until the user completes authentication. On email, tell the user to open the link and press "Sign in the browser that requested this": the page also offers "Sign in here", which signs in the browser they clicked from instead of this connection. Terminal states: "verified" (login succeeded), "failed", "expired", "completed_elsewhere" (email only: the user pressed "Sign in here" on the email link's page, so the browser they clicked from is signed in and this connection never will be — tell them so, and start a new login if this connection still needs one).

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.

Input Schema

Name	Required	Description
`email`	No	Email address (required for email channel)
`channel`	Yes	Authentication channel
`phone_number`	No	Phone number in E.164 format (required for SMS channel)

Output Schema

Name	Required	Description
`id`	No
`type`	No
`status`	No	Status of an auth session. `completed_elsewhere` (terminal, no cookies): an email sign-in the person completed in ANOTHER browser by pressing "Sign in here" on the link's page — this session will never become `verified`.
`channel`	No	Authentication channel
`qr_code`	No	Base64-encoded QR code image
`qr_text`	No	UTF-8 text representation of the QR code for terminal/agent display
`user_id`	No
`deep_link`	No
`expires_at`	No
`verified_at`	No
`instructions`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.7.2Nov 6, 2026

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

addedInput schema / properties / email / pattern

Added value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "channel": {
+      "description": "Authentication channel"
+    },
+    "deep_link": {},
+    "expires_at": {},
+    "id": {},
+    "instructions": {},
+    "qr_code": {
+      "description": "Base64-encoded QR code image"
+    },
+    "qr_text": {
+      "description": "UTF-8 text representation of the QR code for terminal/agent display"
+    },
+    "status": {
+      "description": "Status of an auth session. `completed_elsewhere` (terminal, no cookies): an email sign-in the person completed in ANOTHER browser by pressing \"Sign in here\" on the link's page — this session will never become `verified`."
+    },
+    "type": {},
+    "user_id": {},
+    "verified_at": {}
+  },
+  "type": "object"
+}

First observedv1.1.0Sep 9, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=false and destructiveHint=false, yet the description discloses far more: delivery failure surfaces as an error with no session created, the four terminal states including the email-only completed_elsewhere trap, and the constraint that the user never sees tool output. That is real behavioral context beyond structured fields.

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 action and return payload, then organized into numbered steps with per-channel branches. It is long for a three-parameter tool and repeats the 'which field to show depends on channel' point more than once, with heavy all-caps emphasis, but nearly every sentence carries an actionable instruction.

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 lifecycle an agent needs: inputs, per-channel returns, the render_auth_link handoff, the polling step, error behavior, and terminal states. Even though an output schema exists, the description adds the sequencing and user-facing presentation rules the schema cannot express.

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 would be 3; the description nonetheless ties each parameter to a channel outcome (phone_number for SMS, email for email) and frames channel choice as determining the entire response shape. It stops short of adding format detail beyond the schema's E.164 and email pattern notes.

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?

Specific verb and resource: 'Start a login session by sending an authentication challenge' across four named channels, plus the return payload per channel. It clearly separates itself from wait_for_login, render_auth_link and the start_2fa / start_add_* siblings by being the entry point of a login (not a 2FA or contact-add) flow.

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 numbered procedure, names the alternative tools at each step (render_auth_link, wait_for_login), and states when NOT to use them (sms deep_link is empty and render_auth_link will reject it; do not call wait_for_login after challenge_delivery_failed). Channel-by-channel branches leave almost nothing to inference.

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

Deploy Server