Skip to main content
Glama
Sign In
@proof-holdings/mcp-server

@proof-holdings/mcp-server

Official
by ProofHoldings
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

revoke_proof

Destructive

Revoke a proof permanently by public handle or verification ID so it no longer validates anywhere; use suspend for temporary stops.

Instructions

Revoke a proof by its public handle (ph_ctl_* / ph_dlg_*) or a verification ID — the same addresses get_proof_status takes. The proof token will no longer validate anywhere: the status endpoint, the public validator, the revocation list and the Token Status List all report it revoked. A domain CONTROL proof (a ph_ctl_* of a domain) also revokes, for good, every delegation issued from it; for a domain you own, every proof of the domain is revoked and the domain needs re-verification. The API key needs proofs:write, plus delegations:write while the revocation reaches live delegations — for a domain you own, any live delegation of the domain, whichever of its handles you name (the refusal names the scope and the count). A handle revoked before the domain was verified again does not reach the new proof: revoke that one by its own handle. Otherwise it revokes the PROOF only — the asset or consent it is about stays. Need a temporary stop? Use suspend_proof instead. Cannot be undone.

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

NameRequiredDescriptionDefault
idYesPublic proof handle (ph_ctl_* / ph_dlg_*) or verification ID
reasonNoWhy the proof is revoked, one of: user_request, fraud, key_compromise, asset_transferred, other. A delegation proof (ph_dlg_*) refuses asset_transferred. The API refuses any other value. Defaults to user_request.

Output Schema

NameRequiredDescriptionDefault
reasonNo
successNo
proof_idNoPublic proof handle (`ph_ctl_*`/`ph_dlg_*`). Present when the proof was addressed by handle.
principalNoControl proofs only: the domain the proof is about.
proof_typeNoWhich record carries the revoked proof (`verification`, `user_asset`, `verification_request`, `delegation`, …). Present when the proof was addressed by handle.
revoked_atNo
owned_domainNoControl proofs only: true when the account OWNS the domain (a Domain row or a domain asset for the name) and the whole-domain cascade ran — every proof of the domain and every delegation issued from it revoked, the domain demoted to `reverification_required`. False for a bare verification of somebody else's domain: that proof and the delegations anchored on it only.
domain_statusNoControl proofs only: the Domain row's status after the act (`reverification_required` after the cascade); null when the account has no Domain row for the name.
verification_idNoPresent only when the revoked proof belongs to a verification.
delegations_revokedNoControl proofs only: the delegations revoked with the proof. Re-verifying the domain does not bring them back.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.7.2
    • removedInput schema / additionalProperties
      Removed value: -false
    • changedInput schema / properties / reason / description
      Previous value: -"Reason for revocation"New value: +"Why the proof is revoked, one of: user_request, fraud, key_compromise, asset_transferred, other. A delegation proof (ph_dlg_*) refuses asset_transferred. The API refuses any other value. Defaults to user_request."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "delegations_revoked": {
+      "description": "Control proofs only: the delegations revoked with the proof. Re-verifying the domain does not bring them back."
+    },
+    "domain_status": {
+      "description": "Control proofs only: the Domain row's status after the act (`reverification_required` after the cascade); null when the account has no Domain row for the name."
+    },
+    "owned_domain": {
+      "description": "Control proofs only: true when the account OWNS the domain (a Domain row or a domain asset for the name) and the whole-domain cascade ran — every proof of the domain and every delegation issued from it revoked, the domain demoted to `reverification_required`. False for a bare verification of somebody else's domain: that proof and the delegations anchored on it only."
+    },
+    "principal": {
+      "description": "Control proofs only: the domain the proof is about."
+    },
+    "proof_id": {
+      "description": "Public proof handle (`ph_ctl_*`/`ph_dlg_*`). Present when the proof was addressed by handle."
+    },
+    "proof_type": {
+      "description": "Which record carries the revoked proof (`verification`, `user_asset`, `verification_request`, `delegation`, …). Present when the proof was addressed by handle."
+    },
+    "reason": {},
+    "revoked_at": {},
+    "success": {},
+    "verification_id": {
+      "description": "Present only when the revoked proof belongs to a verification."
+    }
+  },
+  "type": "object"
+}
  2. First observedv1.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true, and the description goes well beyond that: it lists every surface that will report the token revoked, states the cascade to live delegations and to all proofs of an owned domain, discloses the required scopes (proofs:write plus delegations:write) and the refusal's contents, and says plainly it cannot be undone. It stops short of describing the response body, but an output schema exists so that burden is lifted.

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?

The core action and identifier space are front-loaded, and the alternative to suspend_proof is placed where an agent will read it. Every sentence carries information, but the middle section is a dense run-on covering cascades, scopes and refusals that would scan faster as separated clauses; length is defensible given the destructive, cascading behavior.

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, cascading operation this covers what an agent needs: what gets revoked, what survives (the asset or consent), the scope requirements, the refusal conditions, and the account/key prerequisite. Return values are handled by the output schema, so no gap remains.

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% and both parameters already carry descriptions including the allowed reason values, so the baseline is 3. The description adds real meaning on top: it clarifies that the identifier space is shared with get_proof_status and warns that a handle revoked before re-verification will not reach the newer proof, which is a non-obvious invocation caveat.

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 and resource ("Revoke a proof") and immediately narrows the accepted identifiers to public handles (ph_ctl_*/ph_dlg_*) or a verification ID, tying them to the same addresses get_proof_status takes. It distinguishes itself from suspend_proof by name, so an agent can tell the two apart without opening either 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 gives an explicit alternative with the condition that selects it: "Need a temporary stop? Use suspend_proof instead." It also spells out when the cascade path applies (domain CONTROL proofs, domains you own) and how to handle the re-verification edge case by revoking the new proof by its own handle.

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

Deploy Server

Other Tools