@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

get_delegation

Read-only

Retrieve a delegation by Mongo ID or ph_dlg handle to get its publishable token and derived effective status/validity, including whether its control proof and expiry still keep it live.

Instructions

Get one of your delegations by Mongo id or ph_dlg_* handle. Returns the stored publishable token plus the DERIVED effective_status/is_valid — the delegation is only as live as the control proof it stands on (a revoked, suspended or expired domain proof invalidates it) and never outlives its own expires_at, whichever comes first.

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": "get_delegation"
  }
}

Input Schema

Name	Required	Description	Default
`id`	Yes	Delegation ID (24-hex Mongo id or ph_dlg_<32 hex> handle)

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.
`token`	No	The signed delegation JWT — the PUBLISHABLE artifact (publish it in your MCP server card under `_meta` → `holdings.proof/delegation`). Same key, algorithm and JWKS as proof tokens
`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"
+    },
+    "token": {
+      "description": "The signed delegation JWT — the PUBLISHABLE artifact (publish it in your MCP server card under `_meta` → `holdings.proof/delegation`). Same key, algorithm and JWKS as proof tokens"
+    }
+  },
+  "type": "object"
+}

First observedv1.1.0Sep 9, 2026

TDQS

A4/5.0

Behavior5/5

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

Goes well beyond readOnlyHint: it discloses that the returned token is the stored publishable one, that effective_status/is_valid are DERIVED, that a revoked/suspended/expired domain proof invalidates the delegation, and that it never outlives its own expires_at. That is exactly the kind of invalidation semantics an agent cannot guess from the schema.

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 capability, followed by the non-obvious derived-status semantics, then a clearly separated ACCESS block. Dense but every sentence carries information; only the identifier-format restatement is redundant.

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?

An output schema exists so return shape needs no prose, and the description still adds the crucial derivation rules plus the auth prerequisite that would otherwise cause a failed call. For a single-param read tool this covers what an agent needs to invoke 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 coverage is 100% and the id property already documents both the 24-hex and ph_dlg_<32 hex> forms with a matching regex, so the description only restates it. The baseline of 3 is appropriate — no additional meaning (e.g. lookup-failure behavior) is conveyed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("Get one of your delegations") and even the accepted identifier forms (Mongo id or ph_dlg_* handle). It does not explicitly differentiate itself from the very close sibling get_delegation_token, leaving the agent to infer that this one returns derived status alongside the token.

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

Usage Guidelines3/5

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

Prerequisite guidance is strong and explicit (Proof account, PROOF_API_KEY, restart, and the notable exclusion that start_login does NOT unlock this tool). What's missing is when to pick this over list_delegations, get_delegation_token, or verify_delegation — usage context is implied by the object-lookup framing but never routed.

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

Deploy Server