@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

create_authorization

Create an authorization request that grants permission to send confirmations to a user through a specified channel; the user must approve it before confirmations are sent.

Instructions

Create a new authorization request. Authorizations grant permission to send confirmations to a user via a specific channel. The user must approve the authorization before confirmations can be sent.

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
`bsuid`	No	WhatsApp Business-Scoped User ID (alternative to phone for WhatsApp channel)
`phone`	Yes	Target phone number in E.164 format (e.g., +15551234567)
`scope`	No	Authorization scope (default: confirmations)
`channel`	Yes	Channel for sending confirmations
`hitl_id`	Yes	HITL configuration ID to link this authorization to
`recipient`	Yes	Channel-specific recipient identifier (chat_id for Telegram, phone/BSUID for WhatsApp)
`expires_in`	No	Expiry in seconds (max 90 days, default 90 days)
`business_name`	No	Deprecated and ignored: the consent message always names the approval setup's sub-account. Leave it out.
`business_profile_id`	No	Sub-account to record on the authorization (does not change the name the person sees)

Output Schema

Name	Required	Description
`id`	Yes	MongoDB ObjectId
`bsuid`	No	WhatsApp Business-Scoped User ID
`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`	Yes
`recipient`	No	Channel-specific recipient identifier (chat_id for Telegram, phone or BSUID for WhatsApp)
`created_at`	Yes
`expires_at`	Yes
`business_name`	Yes	The name the consent message carried: the approval setup's sub-account name, never a name typed in the request.
`authorization_url`	Yes	URL to send to the user for authorization

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.7.2Nov 6, 2026

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

changedInput schema / properties / business_name / description

Previous value: -"Business name displayed to user during authorization"New value: +"Deprecated and ignored: the consent message always names the approval setup's sub-account. Leave it out."

changedInput schema / properties / business_profile_id / description

Previous value: -"Public profile ID for branding"New value: +"Sub-account to record on the authorization (does not change the name the person sees)"

changedInput schema / required

Previous value: -[
-  "hitl_id",
-  "recipient",
-  "phone",
-  "channel",
-  "business_name"
-]New value: +[
+  "hitl_id",
+  "recipient",
+  "phone",
+  "channel"
+]

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "description": "Response from creating an authorization request",
+  "properties": {
+    "authorization_url": {
+      "description": "URL to send to the user for authorization",
+      "type": "string"
+    },
+    "bsuid": {
+      "description": "WhatsApp Business-Scoped User ID",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "business_name": {
+      "description": "The name the consent message carried: the approval setup's sub-account name, never a name typed in the request.",
+      "type": "string"
+    },
+    "channel": {
+      "description": "Channel authorized for sending confirmations",
+      "type": "string"
+    },
+    "created_at": {
+      "type": "string"
+    },
+    "expires_at": {
+      "type": "string"
+    },
+    "hitl_id": {
+      "allOf": [
+        {
+          "type": "string"
+        },
+        {}
+      ]
+    },
+    "id": {
+      "description": "MongoDB ObjectId",
+      "type": "string"
+    },
+    "phone": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "recipient": {
+      "description": "Channel-specific recipient identifier (chat_id for Telegram, phone or BSUID for WhatsApp)",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "scope": {
+      "description": "Scope of the authorization. `identity_challenge` is the Proof of Me scope.",
+      "type": "string"
+    },
+    "status": {
+      "description": "Status of an authorization",
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "status",
+    "hitl_id",
+    "channel",
+    "scope",
+    "business_name",
+    "authorization_url",
+    "expires_at",
+    "created_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?

Annotations only say readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond that — the created object is inert until the end user approves it, and creation requires a Proof account with PROOF_API_KEY configured plus a server restart. It does not cover whether repeated calls create duplicates or how long the pending state lasts, which is why it is not 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?

Two short, front-loaded paragraphs: what the tool creates and the approval semantics first, then the access prerequisite. Every sentence earns its place, though the ACCESS preamble is operational noise for an already-authenticated agent.

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 9 parameters, an output schema, and thin annotations, the definition supplies what the structured fields cannot: the approval workflow and the account prerequisite. It is nearly complete for the calling decision; the remaining gap is the relationship to sibling authorization/confirmation tools.

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?

Schema description coverage is 100%, including enum values, patterns, and the deprecation of business_name, so the schema already carries parameter meaning. The description adds nothing about individual fields (for example, phone versus bsuid per channel), so the baseline 3 applies.

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 uses a specific verb and resource ("Create a new authorization request") and explains the domain concept: an authorization grants permission to send confirmations to a user over a channel, and the user must approve it. That distinguishes it from generic creation tools, but it never names the adjacent siblings it could be confused with (create_confirmation, request_hitl_authorization, create_verification_request), so the differentiation stops short of a 5.

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?

Usage is implied rather than stated: the agent learns an authorization is a prerequisite for sending confirmations, and the ACCESS note usefully excludes start_login as a way to unlock the tool. However, there is no explicit guidance on when to call create_authorization versus request_hitl_authorization or create_confirmation, nor on what to do if an authorization already exists.

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

Deploy Server