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

@proof-holdings/mcp-server

Official
by ProofHoldings
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

get_identity_challenge

Read-only

Retrieve a Proof-Me identity challenge by ID to poll its status and, once resolved, get the proof token and proof_id.

Instructions

Get a Proof-Me identity challenge by ID. Returns its status (pending, confirmed, denied, cancelled, failed, expired, revoked or suspended), the channel the CONFIRM ran on, and — once the person being checked decided — the proof token and its proof_id. Poll this for resolution.

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

NameRequiredDescriptionDefault
idYesIdentity challenge ID

Output Schema

NameRequiredDescriptionDefault
idYes
statusYesThe one status every read reports. `pending` — waiting for the person being checked; `confirmed` — they confirmed; `denied` — they denied; `cancelled` — whoever started the check withdrew it; `failed` — the check could not be delivered; `expired` — nobody answered in time; `revoked` / `suspended` — the confirmation's proof was revoked or suspended (`POST /proofs/{proof_id}/revoke` or `/suspend`; revoking a denial's proof leaves it `denied`), or — `revoked` only — the member being checked was removed from the Circle while the check was still pending, which leaves `proof_id` null. Removing a member is not guaranteed to revoke a confirmation they already gave; revoke that one by its `proof_id`. A proof that merely reached its own expiry still reads `confirmed`; whether its token is still valid is `POST /proofs/validate`'s answer.
channelNoChannel the CONFIRM was dispatched on (GET)
is_drillNoTrue for a drill (scheduled, or started from the dashboard) rather than a real check (GET)
proof_idNoPublic handle of the decision's proof — what `POST /proofs/{proof_id}/revoke` takes. Null until a decision minted one (GET).
circle_idNoThe Circle the check belongs to (GET)
created_atNoISO 8601 timestamp
expires_atNoISO 8601 timestamp
proof_tokenNoSigned proof token, present once the person being checked decided
resolved_atNoISO 8601 timestamp of the decision — the CONFIRM, the DENY, the cancellation or the delivery failure — or null while the check is unanswered and after a timeout.
confirm_channelNoChannel the CONFIRM was dispatched on (POST)
single_channel_warningNoTrue when the account holder has only one channel, so the CONFIRM ran on the same channel as the suspicious contact (degraded)

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": "An identity challenge (Proof of Me)",
+  "properties": {
+    "channel": {
+      "description": "Channel the CONFIRM was dispatched on (GET)",
+      "type": "string"
+    },
+    "circle_id": {
+      "description": "The Circle the check belongs to (GET)",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "confirm_channel": {
+      "description": "Channel the CONFIRM was dispatched on (POST)",
+      "type": "string"
+    },
+    "created_at": {
+      "description": "ISO 8601 timestamp",
+      "type": "string"
+    },
+    "expires_at": {
+      "description": "ISO 8601 timestamp",
+      "type": "string"
+    },
+    "id": {
+      "type": "string"
+    },
+    "is_drill": {
+      "description": "True for a drill (scheduled, or started from the dashboard) rather than a real check (GET)",
+      "type": "boolean"
+    },
+    "proof_id": {
+      "description": "Public handle of the decision's proof — what `POST /proofs/{proof_id}/revoke` takes. Null until a decision minted one (GET).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "proof_token": {
+      "description": "Signed proof token, present once the person being checked decided",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "resolved_at": {
+      "description": "ISO 8601 timestamp of the decision — the CONFIRM, the DENY, the cancellation or the delivery failure — or null while the check is unanswered and after a timeout.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "single_channel_warning": {
+      "description": "True when the account holder has only one channel, so the CONFIRM ran on the same channel as the suspicious contact (degraded)",
+      "type": "boolean"
+    },
+    "status": {
+      "description": "The one status every read reports. `pending` — waiting for the person being checked; `confirmed` — they confirmed; `denied` — they denied; `cancelled` — whoever started the check withdrew it; `failed` — the check could not be delivered; `expired` — nobody answered in time; `revoked` / `suspended` — the confirmation's proof was revoked or suspended (`POST /proofs/{proof_id}/revoke` or `/suspend`; revoking a denial's proof leaves it `denied`), or — `revoked` only — the member being checked was removed from the Circle while the check was still pending, which leaves `proof_id` null. Removing a member is not guaranteed to revoke a confirmation they already gave; revoke that one by its `proof_id`. A proof that merely reached its own expiry still reads `confirmed`; whether its token is still valid is `POST /proofs/validate`'s answer.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "status"
+  ],
+  "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?

readOnlyHint=true is consistent with a 'get' tool, and the description adds real context beyond annotations: the full status enumeration, the fact that the proof token only materializes once the subject has decided, and a prominent authentication precondition with remediation steps. Its one gap is that it doesn't say whether the token/status is stable across subsequent polls or how long an expired/revoked challenge remains retrievable.

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 core action and return payload, then polls, then access constraints in a separate labeled block. Slightly verbose in the long status list and the shouting ACCESS block, but no sentence is wasted for an agent that will otherwise fail on auth.

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?

A one-parameter read with an output schema and readOnlyHint — the description covers the decision-relevant extras (status semantics, token timing, auth requirement). Return-shape detail is correctly delegated to the output schema, leaving only poll-interval/expiry guidance unaddressed.

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?

Only one parameter exists and the schema already documents it at 100% coverage with a 24-hex-character pattern, so the schema carries the semantics. The description's 'by ID' phrasing adds nothing beyond that, which is the baseline case for full-coverage schemas.

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 and resource ('Get a Proof-Me identity challenge by ID') and immediately clarifies the scope of the returned object (status, channel, proof token/proof_id). This clearly separates it from the create_identity_challenge sibling, which would produce such an ID.

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?

'Poll this for resolution' gives explicit operational guidance for how the tool is meant to be used, and the ACCESS paragraph explicitly excludes start_login as a path to this tool. It stops short of naming create_identity_challenge as the source of the ID, so the create→poll workflow is only implied.

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