start_2fa_for_action

holdings.proof/mcp-server · Verify this server

Start a 2FA challenge that grants the authenticated user permission to perform a sensitive action. The 2FA must complete on a channel DIFFERENT from the user's last login channel (the backend enforces this). On success a grant is stored keyed by the user id and action_type; middleware on the protected endpoint reads the grant and allows the mutation. Destructive action types (api_key_create, api_key_revoke, api_key_regenerate, api_key_view, account_delete, phone_remove, email_remove, revocation_bulk) are capped at 5min TTL and forced single-use by server policy. Configuration scopes (settings_write, profile_update, templates_write) allow up to 24h TTL and caller-chosen single_use — useful for agents making multiple settings mutations in one session. Agent usage: (1) Attempt the sensitive call; if you get `403 2fa_required` note the `action_type`. (2) Call start_2fa_for_action with that action_type and a channel different from the login channel. (3) Present the challenge: on telegram/whatsapp pass `deep_link` to render_auth_link; on sms show `sms_message` and the number to send it to; on email check the response first: with more than one verified email and no `email_id` given, it answers 200 with `requires_email_selection: true` and `available_emails` — NO session was started and nothing was sent, so ask the user which address and call again with `email_id` rather than telling them to open a mailbox. Never hand `qr_text` to a link renderer — it is the link already rendered as QR art. Print it verbatim inside a fenced code block only when a real terminal needs the QR. (4) Call wait_for_2fa until the session is verified. (5) Retry the original sensitive call. ACCESS: needs a Proof account. Authenticate this client (Claude Code: /mcp → Authenticate), then call this tool again. start_login does NOT open this tool.