@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

create_hitl

Creates a Human-in-the-Loop config to route approval requests to Telegram, WhatsApp, or circle members and define the default timeout for human authorization.

Instructions

Create a HITL (Human-in-the-Loop) config. Defines which messaging channels receive approval requests and the default timeout.

Agent usage: After creating a HITL config, you must call request_hitl_authorization before it can be used with create_confirmation. For Telegram channels, use create_chat_id_discovery first to discover the user's chat ID, then include it in the channel config.

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
`name`	Yes	Human-readable name for this HITL config
`channels`	No	Messaging channels for approval requests (telegram or whatsapp). Either channels or circle_id is required.
`circle_id`	No	Route approvals through this circle's members instead of listed channels (24 hex characters)
`profile_id`	No	The sub-account (24 hex characters) whose branding the approval messages carry; omitted, the primary
`timeout_seconds`	No	Default timeout in seconds (60–86400, default: 3600)

Output Schema

Name	Required	Description
`id`	Yes	MongoDB ObjectId
`name`	No
`status`	Yes	Status of a HITL configuration
`keypair`	Yes	Encryption keypair metadata (null if not configured)
`user_id`	Yes	Owner user ID (useful for SDK encryption AAD)
`channels`	Yes
`circle_id`	No	Backing Circle for a circle-backed Approvals config (null for channel-list configs)
`created_at`	Yes
`profile_id`	No
`updated_at`	Yes
`environment`	Yes
`timeout_seconds`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv1.7.2Nov 6, 2026

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

changedInput schema / properties / channels / description

Previous value: -"Messaging channels for approval requests (telegram or whatsapp)"New value: +"Messaging channels for approval requests (telegram or whatsapp). Either channels or circle_id is required."

removedInput schema / properties / channels / items / anyOf

Removed value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "config": {
-        "additionalProperties": false,
-        "properties": {
-          "chat_id": {
-            "maxLength": 50,
-            "minLength": 1,
-            "type": "string"
-          }
-        },
-        "required": [
-          "chat_id"
-        ],
-        "type": "object"
-      },
-      "type": {
-        "const": "telegram",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "config"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "config": {
-        "additionalProperties": false,
-        "properties": {
-          "bsuid": {
-            "description": "WhatsApp Business-Scoped User ID (e.g. US.abc123...)",
-            "pattern": "^[A-Z]{2}\\.[a-zA-Z0-9]{10,140}$",
-            "type": "string"
-          },
-          "phone_number": {
-            "description": "Phone number in E.164 format",
-            "pattern": "^\\+?[1-9]\\d{6,14}$",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      },
-      "type": {
-        "const": "whatsapp",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "config"
-    ],
-    "type": "object"
-  }
-]

addedInput schema / properties / channels / items / oneOf

Added value: +[
+  {
+    "properties": {
+      "config": {
+        "properties": {
+          "chat_id": {
+            "maxLength": 50,
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "chat_id"
+        ],
+        "type": "object"
+      },
+      "type": {
+        "const": "telegram",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "config"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "config": {
+        "properties": {
+          "bsuid": {
+            "description": "WhatsApp Business-Scoped User ID (e.g. US.abc123...)",
+            "pattern": "^[A-Z]{2}\\.[a-zA-Z0-9]{10,140}$",
+            "type": "string"
+          },
+          "phone_number": {
+            "description": "Phone number in E.164 format",
+            "pattern": "^\\+?[1-9]\\d{6,14}$",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": {
+        "const": "whatsapp",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "config"
+    ],
+    "type": "object"
+  }
+]

addedInput schema / properties / circle_id

Added value: +{
+  "description": "Route approvals through this circle's members instead of listed channels (24 hex characters)",
+  "pattern": "^[0-9a-fA-F]{24}$",
+  "type": "string"
+}

addedInput schema / properties / profile_id

Added value: +{
+  "description": "The sub-account (24 hex characters) whose branding the approval messages carry; omitted, the primary",
+  "pattern": "^[0-9a-fA-F]{24}$",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "name",
-  "channels"
-]New value: +[
+  "name"
+]

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "description": "HITL configuration with messaging channels and timeout",
+  "properties": {
+    "channels": {
+      "items": {
+        "oneOf": [
+          {
+            "additionalProperties": {},
+            "properties": {
+              "config": {
+                "additionalProperties": {},
+                "properties": {
+                  "chat_id": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "chat_id"
+                ],
+                "type": "object"
+              },
+              "type": {
+                "const": "telegram",
+                "type": "string"
+              }
+            },
+            "required": [
+              "type",
+              "config"
+            ],
+            "type": "object"
+          },
+          {
+            "additionalProperties": {},
+            "properties": {
+              "config": {
+                "additionalProperties": {},
+                "properties": {
+                  "bsuid": {
+                    "type": "string"
+                  },
+                  "phone_number": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "type": {
+                "const": "whatsapp",
+                "type": "string"
+              }
+            },
+            "required": [
+              "type",
+              "config"
+            ],
+            "type": "object"
+          }
+        ]
+      },
+      "type": "array"
+    },
+    "circle_id": {
+      "description": "Backing Circle for a circle-backed Approvals config (null for channel-list configs)",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "created_at": {
+      "type": "string"
+    },
+    "environment": {
+      "type": "string"
+    },
+    "id": {
+      "description": "MongoDB ObjectId",
+      "type": "string"
+    },
+    "keypair": {
+      "anyOf": [
+        {
+          "additionalProperties": {},
+          "properties": {
+            "has_backup_wrapper": {
+              "type": "boolean"
+            },
+            "has_encrypted_private_key": {
+              "type": "boolean"
+            },
+            "has_wrapped_dek": {
+              "type": "boolean"
+            },
+            "kid": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "kid",
+            "has_encrypted_private_key",
+            "has_wrapped_dek",
+            "has_backup_wrapper"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Encryption keypair metadata (null if not configured)"
+    },
+    "name": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "profile_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "status": {
+      "description": "Status of a HITL configuration",
+      "type": "string"
+    },
+    "timeout_seconds": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "updated_at": {
+      "type": "string"
+    },
+    "user_id": {
+      "description": "Owner user ID (useful for SDK encryption AAD)",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "id",
+    "user_id",
+    "channels",
+    "timeout_seconds",
+    "status",
+    "keypair",
+    "environment",
+    "created_at",
+    "updated_at"
+  ],
+  "type": "object"
+}

First observedv1.1.0Sep 9, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds the non-obvious access gate (PROOF_API_KEY must be set and the server restarted) and the lifecycle state that a new config is unusable until authorized. That is real behavioral context beyond structured fields. It does not address naming collisions or what happens on duplicate creation, which keeps it from 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?

Front-loaded with the purpose, then two clearly labeled blocks for agent usage and access gating. Dense but every sentence carries actionable content; the only minor cost is that the ACCESS block is stated in three short fragments rather than one.

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 annotations and an output schema present, the description covers the remaining gaps an agent needs: prerequisite access, mandatory follow-up call, and channel-specific discovery. It leaves unstated whether channels and circle_id are mutually exclusive and what happens when neither is supplied, which matters because only 'name' is in the schema's required list.

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 meaning the schema cannot: it tells the agent where a Telegram chat_id value comes from (create_chat_id_discovery) and frames timeout_seconds as a default rather than a per-request override. The either/or relationship between channels and circle_id is only asserted in the schema text, not reinforced here.

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 ('Create a HITL config') and immediately scopes what the resource governs: which messaging channels receive approval requests and the default timeout. This separates it cleanly from request_hitl_authorization, create_confirmation, and update_hitl, which are named in the usage section.

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 sequencing rules with named siblings: request_hitl_authorization must be called after creation and before create_confirmation will work, and Telegram channels require create_chat_id_discovery first. It also rules out a plausible-but-wrong path by stating start_login does NOT unlock this tool.

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

Deploy Server