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

@proof-holdings/mcp-server

Official
by ProofHoldings
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

create_identity_challenge

Create a cross-channel identity challenge for an enrolled Circle member to confirm or deny a suspicious contact on another messaging channel. Poll the returned ID for the result.

Instructions

Create a Proof-Me cross-channel identity challenge (CONFIRM) for an enrolled Circle member. The account holder approves/denies on a channel different from the one the suspicious contact reached the member on.

Agent usage: poll get_identity_challenge with the returned ID until it leaves pending (confirmed, denied, cancelled, failed, expired or revoked).

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
circle_idYesCircle that holds the member
member_idYesEnrolled Circle member initiating the check
suspicious_channelNoChannel the suspicious contact reached the member on; defaults to the member channel

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. Changed6 schema fields changedv1.6.0
    • removedInput schema / properties / challenger_id
      Removed value: -{
-  "description": "Enrolled challenger initiating the check",
-  "pattern": "^[0-9a-fA-F]{24}$",
-  "type": "string"
-}
    • addedInput schema / properties / circle_id
      Added value: +{
+  "description": "Circle that holds the member",
+  "pattern": "^[0-9a-fA-F]{24}$",
+  "type": "string"
+}
    • removedInput schema / properties / hitl_id
      Removed value: -{
-  "description": "HITL config that holds the challenger",
-  "pattern": "^[0-9a-fA-F]{24}$",
-  "type": "string"
-}
    • addedInput schema / properties / member_id
      Added value: +{
+  "description": "Enrolled Circle member initiating the check",
+  "pattern": "^[0-9a-fA-F]{24}$",
+  "type": "string"
+}
    • changedInput schema / properties / suspicious_channel / description
      Previous value: -"Channel the suspicious contact reached the challenger on; defaults to the challenger channel"New value: +"Channel the suspicious contact reached the member on; defaults to the member channel"
    • changedInput schema / required
      Previous value: -[
-  "hitl_id",
-  "challenger_id"
-]New value: +[
+  "circle_id",
+  "member_id"
+]
  3. First observedv1.1.0

TDQS

A4.3/5.0
Behavior5/5

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

Goes well beyond annotations: discloses that it is asynchronous with a defined terminal-state set (confirmed, denied, cancelled, failed, expired, revoked), that the approval happens on a channel different from the suspicious one, and that authentication requires PROOF_API_KEY plus a server restart. The explicit note that start_login does NOT unlock this tool is unusually valuable context for an agent avoiding a failed call loop.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight blocks — what it does, the approval mechanic, the agent polling loop, and the access prerequisite — with the purpose front-loaded and no filler sentences. Every line carries actionable information.

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?

An output schema exists, so return values need not be explained, and the description still covers prerequisites, async behavior, and terminal states. It omits polling cadence/backoff and failure recovery, which an agent managing a multi-second wait would want.

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 real semantics: the suspicious_channel parameter is relational — it drives which channel the account holder must be reached on, namely one different from it. It still does not explain circle_id/member_id relationships beyond what the schema already states.

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?

Names a specific verb and resource: create a Proof-Me cross-channel identity challenge (CONFIRM) for an enrolled Circle member, and the second sentence explains the cross-channel mechanic that makes this distinct from a plain confirmation. It stops short of naming a concrete sibling (create_confirmation, create_multi_channel_verification) as the alternative, so differentiation is implied rather than explicit.

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?

Gives a clear operational workflow (poll get_identity_challenge with the returned ID until it leaves pending) and states the precondition that the member must be enrolled in a Circle. It does not say when to prefer this over the other confirmation/verification tools or when it is inappropriate.

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