Skip to main content
Glama
Sign In
@proof-holdings/mcp-server

@proof-holdings/mcp-server

Official
by ProofHoldings
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

wait_for_login

Read-only

Poll a login session until the user completes authentication. Returns a terminal status such as verified, failed, or expired, or pending if the wait ran out.

Instructions

Poll a login session until the user completes authentication. Uses exponential backoff (2s initial, 1.5x, 30s max) with jitter.

Agent usage: Call this after start_login with the returned session ID. Terminal states: "verified" (login succeeded — this server keeps the session for this connection and signs your own account records with it: emails, phones, domains, API keys, 2FA, DNS credentials, verification requests, your public profile's username and proof list), "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). A result with status "pending" means the wait ran out before the user finished — call this tool again with the same id.

Before calling this for a challenge you created, make sure your reply text already shows the user what to act on — the link itself, the SMS text and number, or a note to check their inbox; a link that appeared only in a tool result is one they never saw.

Input Schema

NameRequiredDescriptionDefault
idYesAuth session ID from start_login
timeout_secondsNoMaximum wait time in seconds (default: 50, max: 600). Keep it under your MCP client's request timeout (the SDK default is 60 s) — a longer wait is cut off by the client while the server is still polling. On timeout the tool answers status "pending"; call it again with the same identifier.

Output Schema

NameRequiredDescriptionDefault
idNo
typeNo
statusNo"pending" when the wait ran out before a terminal state; otherwise the resource's own status
channelNoAuthentication channel
messageNoOn timeout: what to do next (call the tool again with the same identifier)
qr_codeNoBase64-encoded QR code image
qr_textNoUTF-8 text representation of the QR code for terminal/agent display
user_idNo
deep_linkNo
expires_atNo
last_statusNoOn timeout: the last non-terminal status observed, or null when none was
verified_atNo
instructionsNo
waited_secondsNoOn timeout: seconds actually waited
timeout_secondsNoOn timeout: the wait budget this call was given

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.7.2
    • removedInput schema / additionalProperties
      Removed value: -false
    • 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": {},
+    "last_status": {
+      "description": "On timeout: the last non-terminal status observed, or null when none was"
+    },
+    "message": {
+      "description": "On timeout: what to do next (call the tool again with the same identifier)"
+    },
+    "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": "\"pending\" when the wait ran out before a terminal state; otherwise the resource's own status"
+    },
+    "timeout_seconds": {
+      "description": "On timeout: the wait budget this call was given"
+    },
+    "type": {},
+    "user_id": {},
+    "verified_at": {},
+    "waited_seconds": {
+      "description": "On timeout: seconds actually waited"
+    }
+  },
+  "type": "object"
+}
  2. First observedv1.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true; the description goes far beyond by disclosing the backoff schedule (2s initial, 1.5x, 30s max, jitter) and enumerating all four terminal states with consequences. The "completed_elsewhere" explanation (email-only, browser becomes signed in, this connection never will, start a new login) is exactly the kind of non-obvious behavioral context an agent cannot infer elsewhere.

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 purpose and backoff, then a labelled "Agent usage:" block that keeps the guidance scannable. The terminal-state sentence is dense and parenthetical, but every clause carries distinct information (state name, meaning, required agent action).

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: prerequisite tool, polling/retry semantics, all terminal outcomes and what to do for each, and the user-facing side effect of showing the challenge link. With an output schema present, no return-shape explanation is required and none 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 both parameters are already documented. The description still adds value by framing the id as reusable across retries and explaining that a wait exceeding the client's request timeout surfaces as "pending" rather than a failure — reinforcing the schema's timeout note with operational intent.

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?

Opens with a specific verb+resource: "Poll a login session until the user completes authentication." It is clearly distinguishable from the many sibling waiters (wait_for_2fa, wait_for_session, wait_for_verification) because it names the login-session object and ties it to start_login's returned ID.

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?

Explicitly states the sequencing ("Call this after start_login with the returned session ID") and gives a retry rule: a "pending" result means call again with the same id. It also adds a pre-call obligation — surface the link/SMS/inbox note in the reply text before polling — which is real routing guidance, not filler.

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

Deploy Server

Other Tools