@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

start_2fa_for_action

Start a 2FA challenge to authorize a sensitive action after an API call returns 403 2fa_required, using a channel different from the user's last login.

Instructions

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, phone_primary, email_primary, revocation_bulk, domain_remove, profile_delete) are capped at 5min TTL and forced single-use by server policy. A step-up for revocation_bulk, phone_remove, email_remove, domain_remove, profile_delete or account_delete is bound to targets — the exact ids the protected call will carry. 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.

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, then call this tool again. start_login does NOT open this tool.

Input Schema

Name	Required	Description
`channel`	Yes	Channel for the 2FA challenge — must differ from the user's last login channel
`targets`	No	The ids the step-up is FOR — the grant is bound to exactly these and refused for any other request (`reason: target_mismatch`). revocation_bulk: the asset id you will pass to revoke_asset (one code per asset); phone_remove / email_remove: the phone or email record id; domain_remove: the domain id; profile_delete: the sub-account id; account_delete: your own user id (get_current_user). Leave out for the other action types.
`email_id`	No	Optional: specific UserEmail id for email-channel 2FA
`phone_id`	No	Optional: specific UserPhone id for phone-channel 2FA
`single_use`	No	Whether the grant is consumed on first use. Server forces true for destructive action types. Defaults to true.
`action_type`	Yes	The sensitive action the 2FA grant will authorize: any action type the API documents. The server caps each by its policy: destructive types (e.g. api_key_, _remove, revocation_bulk, account_delete) to 5 min TTL and single use; configuration scopes (e.g. settings_write, webhook_write) up to 24h with caller-chosen single_use.
`ttl_seconds`	No	Requested grant lifetime in seconds. Server caps to 300s for destructive action types, 86400s for configuration scopes. Defaults to 300 if omitted.

Output Schema

Name	Required	Description
`email`	No	The address the code went to, masked (`email` only)
`status`	No
`channel`	No
`message`	No
`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`)
`email_sent`	No	`true` when the code was emailed (`email` only)
`expires_at`	No
`session_id`	No
`sms_message`	No	The message to send (`sms` only)
`instructions`	No	One line telling the person what to do
`available_emails`	No	The addresses the code may go to; call again with one of their ids as `email_id`
`requires_email_selection`	No	Always `true`: no session was started, pick an address and start again
`second_method_recommended`	No	Present (true) when the step-up uses the channel the account signed in with, because the account has no other; adding a second channel is recommended

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.7.2Nov 6, 2026

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

changedInput schema / properties / action_type / description

Previous value: -"The sensitive action the 2FA grant will authorize. Destructive scopes (api_key_*, account_delete, phone_remove, email_remove, phone_primary, email_primary, revocation_bulk, domain_remove, profile_delete) are capped at 5 min TTL + forced single-use. Configuration scopes (settings_write, profile_update, templates_write) allow up to 24h TTL with caller-chosen single_use. See config/twoFAPolicy.ts on the backend for the canonical policy."New value: +"The sensitive action the 2FA grant will authorize: any action type the API documents. The server caps each by its policy: destructive types (e.g. api_key_*, *_remove, revocation_bulk, account_delete) to 5 min TTL and single use; configuration scopes (e.g. settings_write, webhook_write) up to 24h with caller-chosen single_use."

changedInput schema / properties / action_type / enum

Previous value: -[
-  "api_key_create",
-  "api_key_revoke",
-  "api_key_regenerate",
-  "api_key_view",
-  "phone_remove",
-  "email_remove",
-  "account_delete",
-  "revocation_bulk",
-  "domain_remove",
-  "profile_delete",
-  "phone_primary",
-  "email_primary",
-  "settings_write",
-  "profile_update",
-  "templates_write"
-]New value: +[
+  "api_key_view",
+  "api_key_create",
+  "api_key_revoke",
+  "api_key_regenerate",
+  "phone_add",
+  "phone_remove",
+  "phone_primary",
+  "email_add",
+  "email_remove",
+  "email_primary",
+  "account_delete",
+  "master_key_change",
+  "hitl_key_rotate",
+  "revocation_bulk",
+  "settings_write",
+  "profile_update",
+  "templates_write",
+  "webhook_write",
+  "delegation_lifecycle",
+  "company_update",
+  "domain_remove",
+  "profile_delete",
+  "account_delete_cancel",
+  "plan_change",
+  "auto_top_up_change"
+]

changedInput schema / properties / targets / description

Previous value: -"The ids the step-up is FOR — the grant is bound to exactly these and refused for any other request (`reason: target_mismatch`). revocation_bulk: the asset id you will pass to revoke_asset (one code per asset); phone_remove / email_remove: the phone or email record id; domain_remove: the domain id; profile_delete: the project id; account_delete: your own user id (get_current_user). Leave out for the other action types."New value: +"The ids the step-up is FOR — the grant is bound to exactly these and refused for any other request (`reason: target_mismatch`). revocation_bulk: the asset id you will pass to revoke_asset (one code per asset); phone_remove / email_remove: the phone or email record id; domain_remove: the domain id; profile_delete: the sub-account id; account_delete: your own user id (get_current_user). Leave out for the other action types."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "available_emails": {
+      "description": "The addresses the code may go to; call again with one of their ids as `email_id`"
+    },
+    "channel": {},
+    "deep_link": {
+      "description": "Opens Telegram or WhatsApp with what the person sends (`telegram`, `whatsapp`)"
+    },
+    "email": {
+      "description": "The address the code went to, masked (`email` only)"
+    },
+    "email_sent": {
+      "description": "`true` when the code was emailed (`email` only)"
+    },
+    "expires_at": {},
+    "instructions": {
+      "description": "One line telling the person what to do"
+    },
+    "message": {},
+    "qr_code": {
+      "description": "Base64-encoded PNG QR code for `deep_link`"
+    },
+    "qr_text": {
+      "description": "UTF-8 text QR for `deep_link`, for terminal/agent rendering"
+    },
+    "requires_email_selection": {
+      "description": "Always `true`: no session was started, pick an address and start again"
+    },
+    "second_method_recommended": {
+      "description": "Present (true) when the step-up uses the channel the account signed in with, because the account has no other; adding a second channel is recommended"
+    },
+    "session_id": {},
+    "sms_code": {
+      "description": "The short code the person texts (`sms` only)"
+    },
+    "sms_dids": {
+      "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."
+    },
+    "sms_message": {
+      "description": "The message to send (`sms` only)"
+    },
+    "status": {}
+  },
+  "type": "object"
+}

Changed3 schema fields changedv1.6.0Oct 16, 2026

changedInput schema / properties / action_type / description

Previous value: -"The sensitive action the 2FA grant will authorize. Destructive scopes (api_key_*, account_delete, phone_remove, email_remove, revocation_bulk) are capped at 5 min TTL + forced single-use. Configuration scopes (settings_write, profile_update, templates_write) allow up to 24h TTL with caller-chosen single_use. See config/twoFAPolicy.ts on the backend for the canonical policy."New value: +"The sensitive action the 2FA grant will authorize. Destructive scopes (api_key_*, account_delete, phone_remove, email_remove, phone_primary, email_primary, revocation_bulk, domain_remove, profile_delete) are capped at 5 min TTL + forced single-use. Configuration scopes (settings_write, profile_update, templates_write) allow up to 24h TTL with caller-chosen single_use. See config/twoFAPolicy.ts on the backend for the canonical policy."

changedInput schema / properties / action_type / enum

Previous value: -[
-  "api_key_create",
-  "api_key_revoke",
-  "api_key_regenerate",
-  "api_key_view",
-  "phone_remove",
-  "email_remove",
-  "account_delete",
-  "revocation_bulk",
-  "settings_write",
-  "profile_update",
-  "templates_write"
-]New value: +[
+  "api_key_create",
+  "api_key_revoke",
+  "api_key_regenerate",
+  "api_key_view",
+  "phone_remove",
+  "email_remove",
+  "account_delete",
+  "revocation_bulk",
+  "domain_remove",
+  "profile_delete",
+  "phone_primary",
+  "email_primary",
+  "settings_write",
+  "profile_update",
+  "templates_write"
+]

addedInput schema / properties / targets

Added value: +{
+  "description": "The ids the step-up is FOR — the grant is bound to exactly these and refused for any other request (`reason: target_mismatch`). revocation_bulk: the asset id you will pass to revoke_asset (one code per asset); phone_remove / email_remove: the phone or email record id; domain_remove: the domain id; profile_delete: the project id; account_delete: your own user id (get_current_user). Leave out for the other action types.",
+  "items": {
+    "maxLength": 256,
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 25,
+  "minItems": 1,
+  "type": "array"
+}

First observedv1.1.0Sep 9, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Well beyond the annotations, it discloses TTL caps by action class (5 min for destructive, up to 24h for configuration scopes), server-forced single_use, the channel-must-differ enforcement, the target_mismatch refusal, and the silent email-selection branch where no session is started. It also warns that tool results are folded away by most clients, which changes how the agent must surface the link or SMS text. The destructiveHint=false annotation refers to this tool, which only mints a grant, so the discussion of destructive action types is not a contradiction.

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-loads purpose, then policy, then the numbered agent workflow, so a reader can stop early. It is dense and long, and a few items are duplicated between description and schema (TTL caps, single_use forcing, targets binding), but nearly every sentence carries operational information an agent would otherwise get wrong.

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?

For a 7-parameter, policy-heavy step-up tool it covers everything that matters: auth prerequisite (PROOF_API_KEY, restart), the full call sequence, per-channel presentation, the email-selection edge case, and the qr_text pitfall. An output schema exists, yet it still clarifies the response fields that drive branching behavior.

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 already 100%, so the bar is adding meaning: it does, by tying targets to the exact ids the protected call will carry (one code per asset for revocation_bulk, get_current_user for account_delete) and by explaining that single_use and ttl_seconds are overridden by server policy. Most of this restates the schema's own parameter descriptions, so the added value is real but partial.

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

Purpose4/5

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

States a specific verb and resource: 'Start a 2FA challenge that grants the authenticated user permission to perform a sensitive action,' plus the mechanism (grant keyed by user id and action_type, read by middleware). It clearly differs from the login-2FA siblings, but it never names start_2fa / verify_2fa / wait_for_2fa as the alternatives it is not, leaving the agent to infer the distinction from the action-bound framing.

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 five-step loop (attempt call, catch 403 2fa_required, start challenge, present it, wait, retry) with concrete alternatives per channel: render_auth_link for deep_link, sms_message for sms, and re-calling with email_id instead of telling the user to check a mailbox. It also states a hard exclusion: 'start_login does NOT open this tool.'

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

Deploy Server