@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

create_webhook_endpoint

Add a webhook endpoint to receive Proof events for all or selected sub-accounts, with configurable event subscriptions. The response returns the signing secret, so store it immediately.

Instructions

Add a webhook endpoint. An event reaches every active endpoint whose scope includes the event's sub-account and whose events match; an account-level event reaches "all"-scope endpoints only. An account still delivering to the single webhook URL in its settings is moved onto endpoints by this call (that URL becomes an "all"-scope endpoint with the same secret and events). The response carries the endpoint's signing secret — this and rotate_webhook_endpoint_secret are the only times it is returned, so store it now. Deliveries carry an HMAC-SHA256 X-Proof-Signature over "." made with it.

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
`url`	Yes	HTTPS URL deliveries are sent to, at most 2000 characters. Private, loopback and link-local addresses are refused.
`scope`	Yes	"all" serves every sub-account, present and future, plus account-level events; "selected" serves only the sub-accounts in profile_ids
`events`	No	Subscription patterns (at most 32): an exact event type, a family wildcard such as "proof.", or "". An empty list means every event.
`status`	No	A disabled endpoint receives nothing
`description`	No	Your own label for the endpoint, at most 200 characters; null clears it
`profile_ids`	No	Sub-account ids, 24 hex characters each, at most 100. At least one when scope is "selected"; none when scope is "all".

Output Schema

Name	Required	Description
`id`	No	MongoDB ObjectId
`url`	No	HTTPS URL deliveries are POSTed to, at most 2000 characters. Private, loopback and link-local addresses are refused.
`scope`	No	`all` — every sub-account, present and future, plus account-level events. `selected` — only the sub-accounts in `profile_ids`; account-level events never reach it.
`events`	No
`legacy`	No	The endpoint converted from the account's single webhook URL — the one the deprecated `/me/settings` webhook block reads and writes.
`secret`	No	The signing secret — returned only in this response. Store it now.
`status`	No	A `disabled` endpoint receives nothing; its history and secret are kept.
`created_at`	No
`secret_set`	No	Whether the endpoint has a signing secret (always true).
`updated_at`	No
`description`	No
`profile_ids`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.7.2Nov 6, 2026

TDQS

A4.2/5.0

Behavior3/5

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds substantial behavior beyond them: the side effect of moving a legacy settings URL onto an 'all'-scope endpoint with the same secret, and the one-time disclosure of the signing secret. However, the closing paragraph discloses a hard access prerequisite (PROOF_API_KEY must be set and the server restarted) that is not captured by any annotation and would block every call until satisfied — that materially changes the tool's operability and warrants flagging rather than full credit.

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 action, then routing semantics, then the secret-handling warning, then access. Sentences are dense but each carries information; the HMAC signature format is useful but slightly tangential to the create operation itself.

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?

Output schema exists, so return values needn't be enumerated, yet the description correctly highlights the one return detail that matters operationally — the signing secret is shown only here and via rotate_webhook_endpoint_secret. Combined with routing rules and access prerequisites, an agent has everything needed to call it correctly.

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%, so scope, events, status and profile_ids are already well documented with enums and constraints. The description reinforces the meaning of scope ('all' vs sub-account coverage) and event matching, but adds little per-parameter detail beyond the schema baseline.

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?

Opens with a specific verb and resource ('Add a webhook endpoint') and immediately distinguishes itself from the sibling update/list/delete endpoint tools by describing creation semantics and delivery routing. The agent can tell what is being created and what it affects without opening the schema.

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 context for when this fires: an event reaches every active endpoint whose scope includes the sub-account, account-level events reach only 'all'-scope endpoints, and legacy single-URL accounts are migrated by this call. It also names the alternative ('rotate_webhook_endpoint_secret') for retrieving the secret again and explicitly rules out an adjacent tool ('start_login does NOT open this tool'), which is exactly the kind of exclusion an agent needs.

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

Deploy Server