Proof Holdings

get_delegation

Read-only

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. Authenticate this client (Claude Code: /mcp → Authenticate), 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.

Changed1 schema field changedNov 5, 2026

addedOutput schema / properties / scope / description

Added value: +"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."

Changed1 schema field changedNov 2, 2026

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": {},
+    "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"
+}

Changed1 schema field changedOct 26, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
First observedSep 19, 2026

TDQS

A4/5.0

Behavior5/5

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

Consistent with readOnlyHint=true: described purely as a retrieval. Beyond the annotation it discloses the payload (stored publishable token), the presence of DERIVED fields effective_status/is_valid, and the derivation rule — a revoked, suspended, or expired domain control proof invalidates the delegation, and the delegation never outlives its own expires_at, whichever occurs first. That is exactly the non-obvious semantics an agent needs before trusting the returned status.

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 core action in the first clause, then the derived-status caveat, with auth constraints isolated in their own block — good structure for a two-paragraph description. Minor slack in phrases like "whichever comes first" and some redundancy between the token mention here and get_delegation_token's territory.

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?

Even though an output schema exists and return values needn't be spelled out, the description still explains the non-obvious derived fields and their invalidation conditions, and it adds the authenticated-access prerequisite that the schema and annotations cannot convey. For a single-parameter read tool, nothing an agent needs in order to call it correctly is missing.

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 single id parameter's description already documents both accepted formats, so the description's restatement of "Mongo id or ph_dlg_* handle" adds no new information. With the schema doing the full job, the baseline of 3 applies.

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?

The description uses a specific verb plus resource ("Get one of your delegations") and pins down the accepted identifier forms (24-hex Mongo id or ph_dlg_* handle), so the agent knows exactly what record type is returned. It does not, however, distinguish itself from the closely-named siblings get_delegation_token or verify_delegation, which an agent scanning the tool list could easily confuse it with.

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?

Usage context is implied by the identifier requirement and made explicit for auth: it states a Proof account is required, that the client must be authenticated, and that start_login does NOT open this tool — a genuinely useful prerequisite. But there is no guidance on when to call this versus list_delegations, get_delegation_token, or verify_delegation, which is the real selection risk here.

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

All Proof Holdings tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.