Skip to main content
There is no agent poll API for approvals. By default, the phone app talks to the node and you retry the tool after the user decides. A live MCP request can opt into waiting on the existing tool call instead.

When you get approval_required

Tool result JSON (inside MCP content) looks like:
match_code is two digits (00–99). Default prompt TTL is about 300 s.

What to show the user

  1. Your verified agent domain (from key verification — not a marketing name).
  2. The match code, so they can confirm the phone prompt is the same request.
Pattern is CIBA-like: you initiate; they approve on another device; no OAuth redirect.

How to retry

Wait at least retry_after_seconds (often 5) before retrying. Do not spin.

Hold a live request

Add this header to a live /mcp request:
The timeout header is optional and is capped by the approval TTL and 90 seconds. When approved, the node completes the held tool call, including one-shot excerpt and send approvals. A denial returns denied. If the hold times out, the result is the normal approval_required object with retry_after_seconds: 5. This is opt-in and only applies to live MCP. Without the header, the retry contract above is unchanged. Intermediaries and client HTTP timeouts must allow the requested hold duration.

Limits

Do not

  • Call /papi/* (phone API — not for agents).
  • Expect /mcp to return a capability biscuit on approval.
  • Hide the match code or substitute a different identity string.