@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

get_authorization

Read-only

Retrieve an authorization by ID to check its current status and usage statistics, enabling you to monitor or verify delegated access.

Instructions

Get an authorization by ID. Returns the current state of the authorization including status and usage statistics.

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

Name	Required	Description	Default
`id`	Yes	Authorization ID

Output Schema

Name	Required	Description
`id`	Yes	MongoDB ObjectId
`bsuid`	No	WhatsApp Business-Scoped User ID
`label`	No	Owner-assigned human label for this approver (F22); null when unset. Surfaces lead with it, falling back to the masked recipient.
`phone`	No
`scope`	Yes	Scope of the authorization. `identity_challenge` is the Proof of Me scope.
`status`	Yes	Status of an authorization
`channel`	Yes	Channel authorized for sending confirmations
`hitl_id`	No
`enrolled`	Yes	Whether the approver has enrolled an encryption key. A confirmation can be sealed to an approver only once this is true; consent alone (`status: active`) is not enough.
`circle_id`	No
`denied_at`	No	When the recipient refused — the mirror of `authorized_at` for a `denied` row (a challenger cancellation stamps it too). Absent unless the authorization was denied; before it existed such a row carried no decision time at all, only `updated_at`.
`recipient`	No	Channel-specific recipient identifier (chat_id for Telegram, phone or BSUID for WhatsApp)
`created_at`	Yes
`expires_at`	Yes
`revoked_at`	No
`updated_at`	Yes
`proof_token`	No	Signed proof of the recipient's decision, minted when they approved or refused, for both scopes. Absent while no decision has been made.
`last_used_at`	No
`authorized_at`	No
`business_name`	Yes
`verification_id`	No	MongoDB ObjectId
`revocation_reason`	No
`confirmations_sent`	Yes
`recipient_display_name`	Yes	The approver's own messenger name ("First Last @username"), captured when they approved over Telegram; null when none was captured. Chosen by the approver, not verified.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.7.2Nov 6, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "description": "Authorization granting permission to send confirmations via a specific channel",
+  "properties": {
+    "authorized_at": {
+      "type": "string"
+    },
+    "bsuid": {
+      "description": "WhatsApp Business-Scoped User ID",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "business_name": {
+      "type": "string"
+    },
+    "channel": {
+      "description": "Channel authorized for sending confirmations",
+      "type": "string"
+    },
+    "circle_id": {
+      "allOf": [
+        {
+          "type": "string"
+        },
+        {}
+      ]
+    },
+    "confirmations_sent": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "created_at": {
+      "type": "string"
+    },
+    "denied_at": {
+      "description": "When the recipient refused — the mirror of `authorized_at` for a `denied` row (a challenger cancellation stamps it too). Absent unless the authorization was denied; before it existed such a row carried no decision time at all, only `updated_at`.",
+      "type": "string"
+    },
+    "enrolled": {
+      "description": "Whether the approver has enrolled an encryption key. A confirmation can be sealed to an approver only once this is true; consent alone (`status: active`) is not enough.",
+      "type": "boolean"
+    },
+    "expires_at": {
+      "type": "string"
+    },
+    "hitl_id": {
+      "allOf": [
+        {
+          "type": "string"
+        },
+        {}
+      ]
+    },
+    "id": {
+      "description": "MongoDB ObjectId",
+      "type": "string"
+    },
+    "label": {
+      "description": "Owner-assigned human label for this approver (F22); null when unset. Surfaces lead with it, falling back to the masked recipient.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "last_used_at": {
+      "type": "string"
+    },
+    "phone": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "proof_token": {
+      "description": "Signed proof of the recipient's decision, minted when they approved or refused, for both scopes. Absent while no decision has been made.",
+      "type": "string"
+    },
+    "recipient": {
+      "description": "Channel-specific recipient identifier (chat_id for Telegram, phone or BSUID for WhatsApp)",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "recipient_display_name": {
+      "description": "The approver's own messenger name (\"First Last @username\"), captured when they approved over Telegram; null when none was captured. Chosen by the approver, not verified.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "revocation_reason": {
+      "type": "string"
+    },
+    "revoked_at": {
+      "type": "string"
+    },
+    "scope": {
+      "description": "Scope of the authorization. `identity_challenge` is the Proof of Me scope.",
+      "type": "string"
+    },
+    "status": {
+      "description": "Status of an authorization",
+      "type": "string"
+    },
+    "updated_at": {
+      "type": "string"
+    },
+    "verification_id": {
+      "description": "MongoDB ObjectId",
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "status",
+    "channel",
+    "scope",
+    "business_name",
+    "recipient_display_name",
+    "enrolled",
+    "expires_at",
+    "confirmations_sent",
+    "created_at",
+    "updated_at"
+  ],
+  "type": "object"
+}

First observedv1.1.0Sep 9, 2026

TDQS

A3.7/5.0

Behavior4/5

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

readOnlyHint=true is consistent with the read semantics. Beyond the annotation, the description discloses the authorization prerequisite and the configuration step needed before the call can succeed, which annotations cannot convey, plus a hint at payload contents (status, usage statistics). The only gap is that the output schema already covers return shape, so nothing further is added there.

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 behavior is front-loaded in one short sentence, followed by a clearly separated ACCESS block that is actionable rather than filler. The restart instruction is slightly operational and verbose, but it earns its place because the call fails without it.

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 an output schema and readOnlyHint already documenting the return value and safety profile, the description only needed to add the access prerequisite, which it does explicitly. For a one-parameter read tool this is essentially complete, barring a pointer to the listing alternative.

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 required parameter with 100% schema description coverage ('Authorization ID'), so the schema already carries the parameter meaning. The description adds no format, prefix, or sourcing detail for the ID, leaving the schema to do all the work.

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?

The description opens with a specific verb and resource ('Get an authorization by ID') and states the returned data (status and usage statistics), so the operation is unambiguous. It does not distinguish itself from nearby siblings such as list_authorizations or revoke_authorization, but the single-item lookup is self-evident from the name and text.

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

Usage Guidelines3/5

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

The ACCESS paragraph tells the agent a precondition (Proof account, PROOF_API_KEY set, server restart) and explicitly warns that start_login does not unlock this tool. That is useful eligibility guidance, but there is no statement of when to pick this over list_authorizations or get_request_proofs, so usage 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