@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

request_approval_channel_authorization

Request consent from configured Telegram or WhatsApp channels before confirmations can be sent. Returns one authorization entry per recipient with its status, so you know who must approve.

Instructions

Request authorization for an approval channel. Sends consent requests to all configured channels (Telegram/WhatsApp). Users must approve before confirmations can be sent.

Agent usage: This must be completed before create_confirmation will work for this approval channel. The consent request is DELIVERED to each channel — the response carries no link to show. It returns authorizations — one entry per resolved recipient, each with its channel, recipient, authorization_id and status — plus a message. Read the entries rather than assuming: status: 'pending' means consent was just sent and the user must approve in Telegram/WhatsApp itself, while status: 'active' means that recipient had already authorized and nothing was sent to them. An EMPTY array does not mean everyone is authorized — it means no recipient could be resolved at all (usually an approval channel bound to a missing or inactive circle, or channels whose recipient is blank), so nobody was asked and waiting for an approval would hang forever. Do not relay message on that branch: it reads 'All channels already have active or pending authorizations', which is exactly the wrong conclusion. Read the array. After requesting, you can proceed once the user confirms they have approved; get_authorization with an entry's authorization_id reads whether it has turned active.

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>"
    },
    "name": "request_approval_channel_authorization"
  }
}

Input Schema

Name	Required	Description	Default
`id`	Yes	Approval channel ID to request authorization for

Output Schema

Name	Required	Description
`hitl_id`	Yes	MongoDB ObjectId
`message`	Yes
`authorizations`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.10.0Nov 13, 2026

TDQS

A4.9/5.0

Behavior5/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 carries the real burden and does: consent is delivered to each channel, no link is returned, pending vs active semantics, and the dangerous empty-array branch ('nobody was asked and waiting for an approval would hang forever') with explicit instruction not to relay the misleading message. It also discloses the auth requirement (PROOF_API_KEY) and that start_login does not open this tool.

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 purpose, then a clearly delimited 'Agent usage' block and an 'ACCESS' block; the empty-array warning is placed where it matters. It is longer than most definitions and repeats the read-the-array instruction twice, but nearly every sentence prevents a concrete failure mode.

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

Completeness5/5

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

Despite an output schema existing, the description supplies the interpretation layer the schema cannot: per-entry status meanings, the empty-array trap, and the authorization prerequisite. Nothing an agent needs to call this correctly or interpret the result is missing.

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

Parameters5/5

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

Only one parameter and schema description coverage is 100%, so the baseline is 3, but the description adds real meaning by warning that a bound approval channel with a missing/inactive circle or blank recipient yields an empty result — i.e. the quality of the `id` you pass determines whether anyone is actually contacted.

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: 'Request authorization for an approval channel', and immediately scopes what it triggers ('Sends consent requests to all configured channels (Telegram/WhatsApp)'). It also distinguishes the tool from create_confirmation and get_authorization by naming them and their relationship.

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

Usage Guidelines5/5

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

Gives explicit ordering: 'This must be completed before create_confirmation will work for this approval channel', plus the post-condition ('proceed once the user confirms they have approved') and the follow-up alternative (get_authorization with an entry's authorization_id). It also states an access precondition and rules out start_login as a path.

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

Deploy Server