Skip to main content
Glama
ProofHoldings

@proof-holdings/mcp-server

Official
by ProofHoldings
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

start_2fa_for_action

Initiates a 2FA challenge to authorize a sensitive action for an authenticated user, requiring a channel different from their last login; success stores a grant for the protected call.

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

TableJSON Schema
NameRequiredDescriptionDefault
channelYesChannel for the 2FA challenge — must differ from the user's last login channel
targetsNoThe 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.
email_idNoOptional: specific UserEmail id for email-channel 2FA
phone_idNoOptional: specific UserPhone id for phone-channel 2FA
single_useNoWhether the grant is consumed on first use. Server forces true for destructive action types. Defaults to true.
action_typeYesThe 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.
ttl_secondsNoRequested grant lifetime in seconds. Server caps to 300s for destructive action types, 86400s for configuration scopes. Defaults to 300 if omitted.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.6.0
    • 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"
+}
  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=false and destructiveHint=false, and the description goes far beyond them: 5-minute TTL caps and forced single-use for destructive scopes, 24h TTL for config scopes, grant binding to `targets` with `target_mismatch` refusal, the no-session-started email-selection response, and the fact that users never see tool results. It also states the account prerequisite (PROOF_API_KEY). No contradiction with the annotations — the tool starts a challenge, it does not itself destroy anything.

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?

It is long, but the size is justified by the multi-step workflow and the policy branching. Structure is front-loaded: purpose, then policy tiers, then numbered agent steps, then presentation caveats. Some redundancy exists (the destructive/config TTL policy is stated in the prose and again in the action_type and ttl_seconds schema descriptions), which keeps it from a 5.

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?

With no output schema, the description carries the return-value burden and does so — `deep_link`, `sms_message` plus number, the `requires_email_selection` / `available_emails` 200 response, and `qr_text` as pre-rendered QR art. Combined with the auth prerequisite and the surrounding call sequence, nothing an agent needs to invoke this correctly 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 the baseline is 3, but the description adds behavioral meaning beyond the schema: it explains that a step-up for revocation_bulk/phone_remove/email_remove/domain_remove/profile_delete/account_delete is bound to the exact `targets` ids the protected call will carry, and that policy caps override requested ttl_seconds/single_use. The per-parameter schema text largely duplicates this, hence not a 5.

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?

The opening sentence names a specific verb and resource ('Start a 2FA challenge that grants ... permission to perform a sensitive action') and immediately explains the mechanism (grant keyed by user id + action_type, read by middleware on the protected endpoint). It also explicitly separates itself from start_login ('start_login does NOT open this tool') and slots itself into the start_2fa_for_action -> wait_for_2fa -> retry flow, so an agent can place it among the many 2FA siblings.

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?

The 'Agent usage' block gives an explicit five-step when-to-use procedure triggered by a literal `403 2fa_required`, plus a when-not: the channel must differ from the login channel, and email requires an `email_id` selection step first. It also tells the agent what NOT to do (do not tell the user to open a mailbox, never hand `qr_text` to a link renderer).

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