Skip to main content
Glama

Proof Holdings

by holdings.proof
OverviewDiscussionsAdmin

start_2fa_for_action

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. Authenticate this client (Claude Code: /mcp → Authenticate), 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 changed
    • 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 observed

TDQS

A4.8/5.0
Behavior5/5

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

Discloses far more than the annotations, which only state it is not read-only and not itself destructive. It reveals the channel-differs-from-login enforcement, TTL caps (300s destructive / 86400s config), forced single-use for destructive scopes, targets-binding with `reason: target_mismatch`, the no-session-started email-selection edge case, and that clients fold tool results away so the user must be told in the agent's own reply. Also flags the account/auth prerequisite.

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 the purpose before the policy detail, then organized into a numbered workflow and a closing user-visibility caveat. It is long and somewhat dense for a single tool, but nearly every sentence carries operational load, so the length is largely justified rather than padding.

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?

Despite no output schema, the description names the relevant response fields (deep_link, sms_message, qr_text, requires_email_selection, available_emails) and explains how to act on each. Combined with the auth prerequisite and the end-to-end flow, an agent has everything needed to call it and handle the result correctly.

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 baseline is 3, but the description enriches semantics beyond the schema: it explains that step-up grants are bound to the exact `targets` ids the protected call will carry, that destructive scopes key on those ids, and that a channel differing from login is required. It adds a backend policy pointer (config/twoFAPolicy.ts) useful for resolving cap questions.

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?

States a specific verb+resource+scope: starting a 2FA challenge that grants permission for a named sensitive action, and explains the grant mechanism (keyed by user id and action_type, read by endpoint middleware). It is clearly distinguishable from siblings like verify_2fa, wait_for_2fa, and get_2fa_status without opening their schemas.

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?

Provides an explicit five-step agent workflow: attempt the call, observe `403 2fa_required`, call this tool with that action_type and a different channel, present the challenge, wait via wait_for_2fa, retry. It also enumerates per-channel handling (deep_link vs sms_message vs email selection) and warns what not to do with qr_text, leaving almost nothing to inference.

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

All Proof Holdings toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources