Skip to main content
Glama
Sign In
@proof-holdings/mcp-server

@proof-holdings/mcp-server

Official
by ProofHoldings
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

verify_2fa_magic_link

Complete a 2FA challenge using the magic link token from your email; the token itself proves control, so no code submission is needed.

Instructions

Complete a 2FA challenge using a magic link token (received via email). No code submission needed — the token itself is the proof.

ACCESS: needs a Proof account. Set PROOF_API_KEY and restart this server, or sign in with start_login — a session opens this tool — then call this tool again.

Input Schema

NameRequiredDescriptionDefault
tokenYesMagic link token from the verification email

Output Schema

NameRequiredDescriptionDefault
statusYes
action_typeYesThe action the session was started for: one of `TwoFAActionType` for sessions started through this API; admin-console sessions carry internal values.
verified_atNo
already_verifiedNoPresent (true) when the session had already been verified, by its code or another open of the link; no grant is stored by this call and the grant fields are absent
grant_expires_atNoWhen the grant this step-up stored stops being accepted
grant_single_useNoWhether the grant is spent by the first act it allows

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.7.2
    • removedInput schema / additionalProperties
      Removed value: -false
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "description": "The step-up is complete",
+  "properties": {
+    "action_type": {
+      "description": "The action the session was started for: one of `TwoFAActionType` for sessions started through this API; admin-console sessions carry internal values.",
+      "type": "string"
+    },
+    "already_verified": {
+      "description": "Present (true) when the session had already been verified, by its code or another open of the link; no grant is stored by this call and the grant fields are absent",
+      "type": "boolean"
+    },
+    "grant_expires_at": {
+      "description": "When the grant this step-up stored stops being accepted",
+      "type": "string"
+    },
+    "grant_single_use": {
+      "description": "Whether the grant is spent by the first act it allows",
+      "type": "boolean"
+    },
+    "status": {
+      "type": "string"
+    },
+    "verified_at": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "action_type"
+  ],
+  "type": "object"
+}
  2. First observedv1.1.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description's added context matters: it discloses that the token is itself the credential, that no secondary code step exists, and that authentication via PROOF_API_KEY or start_login is required. It omits token lifetime/single-use behavior and what a failed verification returns, which keeps it from a 5.

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?

The core sentence is front-loaded and wastes nothing, and the access requirement is correctly separated into its own block. The phrasing 'a session opens this tool — then call this tool again' is slightly ambiguous about whether the caller is re-entering the same call, which is a small editing blemish rather than bloat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one simple parameter, an output schema covering return values, and minimal annotations, this is close to complete: purpose, the magic-link vs code distinction, and the auth prerequisite are all present. What an agent still cannot infer is token validity/expiry behavior and the remedy on rejection, which for a one-shot credential tool would be worth one more sentence.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema coverage, including the description 'Magic link token from the verification email', so the schema does the heavy lifting and baseline is 3. The tool description only reinforces that the token is the proof; it adds no format, length, or expiry semantics beyond the schema.

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 description gives a specific verb+resource ('Complete a 2FA challenge using a magic link token') and immediately separates it from the code-based path that dominates the surrounding 2FA siblings (verify_2fa, submit_verification_code) with 'No code submission needed — the token itself is the proof.' An agent can tell which 2FA-completion tool to pick without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the trigger condition clearly: call this when you hold a magic-link token delivered by email rather than a numeric code, and it documents the access prerequisite (PROOF_API_KEY or an active session from start_login). It stops short of naming the alternative tool (`verify_2fa`) or describing failure conditions such as an expired or already-used token.

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