@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

revoke_delegation

Destructive

Revoke one delegation while keeping its domain proof and sibling delegations valid. Mirrors the revocation to the proof registry so CRL, status list and status lookup reflect it; repeats succeed.

Instructions

Revoke ONE delegation. The domain control proof and sibling delegations stay valid; the revocation is mirrored into the proof registry so the CRL, status list and public status lookup all see it. Idempotent: a repeat revoke answers success with the same body, both here and through revoke_proof with the ph_dlg_ handle — unlike a PROOF, where a repeat answers already_revoked. The result carries the DERIVED effective_status/is_valid beside the stored status.

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	Delegation ID (24-hex Mongo id or ph_dlg_<32 hex> handle)
`reason`	No	Reason for revocation

Output Schema

Name	Required	Description
`id`	No	MongoDB ObjectId
`scope`	No	Deprecated. Delegation schema 2.0 carries no scope; this array stays for the SDKs released before it: the scope a delegation issued before schema 2.0 was stored with, otherwise empty. Removed in the next major version.
`status`	No	The owner's OWN record — whether they revoked this delegation themselves. Nothing else writes it: neither the control proof dying nor this delegation's own lifetime running out. Liveness is DERIVED and reported separately as `effective_status`. This stored field is also what `?status=` filters on
`delegate`	No	Typed delegate identifier
`is_valid`	No	True only when `effective_status` is `active`. It is a restatement of that field, not a second opinion: expiry is decided once, inside the derivation above
`issued_at`	No
`principal`	No	The proven domain that authorized the delegate — derived from the control proof, never client input
`created_at`	No
`expires_at`	No	Never later than the control proof's own expiry at issuance (effective expiry is min of the two)
`revoked_at`	No
`environment`	No
`control_proof`	No	The control proof handle this delegation points down to
`delegation_id`	No	Stable public handle (`ph_dlg_<32 hex>`) — also the token's `sub`, and accepted by the proof status endpoint
`revoked_reason`	No
`effective_status`	No	DERIVED liveness, computed at read time from BOTH clocks that govern a delegation: the control proof it stands on (cascade rule a — revoked, suspended or expired flows through) and its own `expires_at` (rule b — effective expiry is the earlier of the two). Either one running out reports `expired` here while the delegation's own `status` stays untouched. This is the field to render — `status` alone would show a live badge on a delegation every verifier already rejects

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": {},
+  "properties": {
+    "control_proof": {
+      "description": "The control proof handle this delegation points down to"
+    },
+    "created_at": {},
+    "delegate": {
+      "description": "Typed delegate identifier"
+    },
+    "delegation_id": {
+      "description": "Stable public handle (`ph_dlg_<32 hex>`) — also the token's `sub`, and accepted by the proof status endpoint"
+    },
+    "effective_status": {
+      "description": "DERIVED liveness, computed at read time from BOTH clocks that govern a delegation: the control proof it stands on (cascade rule a — revoked, suspended or expired flows through) and its own `expires_at` (rule b — effective expiry is the earlier of the two). Either one running out reports `expired` here while the delegation's own `status` stays untouched. This is the field to render — `status` alone would show a live badge on a delegation every verifier already rejects"
+    },
+    "environment": {},
+    "expires_at": {
+      "description": "Never later than the control proof's own expiry at issuance (effective expiry is min of the two)"
+    },
+    "id": {
+      "description": "MongoDB ObjectId"
+    },
+    "is_valid": {
+      "description": "True only when `effective_status` is `active`. It is a restatement of that field, not a second opinion: expiry is decided once, inside the derivation above"
+    },
+    "issued_at": {},
+    "principal": {
+      "description": "The proven domain that authorized the delegate — derived from the control proof, never client input"
+    },
+    "revoked_at": {},
+    "revoked_reason": {},
+    "scope": {
+      "description": "Deprecated. Delegation schema 2.0 carries no scope; this array stays for the SDKs released before it: the scope a delegation issued before schema 2.0 was stored with, otherwise empty. Removed in the next major version."
+    },
+    "status": {
+      "description": "The owner's OWN record — whether they revoked this delegation themselves. Nothing else writes it: neither the control proof dying nor this delegation's own lifetime running out. Liveness is DERIVED and reported separately as `effective_status`. This stored field is also what `?status=` filters on"
+    }
+  },
+  "type": "object"
+}

First observedv1.1.0Sep 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare destructiveHint=true; the description goes well beyond them by confirming collateral scope (domain control proof and sibling delegations survive), the downstream registry mirroring into CRL, status list and public lookup, and the idempotent repeat-revoke semantics that differ from PROOF revocation. It also repeats a prerequisite (Proof account) an agent must satisfy before calling.

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?

Effect and idempotency are front-loaded in the first two sentences, with access requirements properly separated into their own block. Slightly sprawling and parenthetical, but every sentence carries a distinct fact.

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?

For a destructive mutation with an output schema present, the description covers blast radius, idempotency, prerequisite auth, and should-be-expected status fields, leaving no significant gap for an agent deciding whether and how to call it.

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 coverage is 100% and both parameters are already documented, including the 24-hex / ph_dlg_ pattern and the reason enum. The description echoes only the ph_dlg_ handle form and adds no new meaning about what `reason` affects downstream, so it sits at the 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?

The description opens with a specific verb plus resource and scope ('Revoke ONE delegation'), and immediately distinguishes the blast radius ('the domain control proof and sibling delegations stay valid'), which is what separates it from revoke_proof in the sibling list. An agent can identify the target object and the exact effect 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?

It states when this applies (revoking a single delegation, versus revoking a PROOF through revoke_proof with a ph_dlg_ handle) and gives an explicit exclusion: 'start_login does NOT open this tool', plus the PROOF_API_KEY prerequisite. That is exactly the when/when-not/alternative structure 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