list_subscription_grants
List the access grants a subscription holds — one per resource and dated window, with the connector, how access was given, where it stands and why it failed if it did.
Read the access ledger for one purchase: every grant the subscription holds, one per resource (and per dated window for a pass), with the connector that gave it, the mode (an invite link, a membership, a role, a task for the creator), the state (pending_identity, pending, held, granted, revoked, failed) and, for a failure, the classified reason and the sentence a creator reads. Use it to answer "does this member actually have access to the channel?" instead of inferring it from the subscription's payment status.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
subscription_id*stringUUID of the subscription whose grants to list.
What it returns
{ "data": [ { "id": "7d1c3e9a-2b64-4f0e-9a58-3c6b1d8e2f47", "subscription_id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4", "resource_id": "c9e21f37-8a4b-4d56-b1e0-2f7c9d3a6e15", "window_id": null, "identity_id": "0c2d8a7e-4b1f-4d3e-9a6b-2f5e8c1d7a90", "connector": "telegram", "mode": "bearer_link", "state": "granted", "reference": "https://t.me/+AbCdEfGhIjKlMnOp", "granted_at": "2026-09-12T10:05:00+00:00", "revoked_at": null, "failure_kind": null, "failure_detail": null, "created_at": "2026-09-12T10:04:58+00:00" } ]}mode is one of bearer_link (a personal invite link the member comes through), membership (the connector added the member), role (a role was assigned) or creator_task (the creator has to do something by hand). reference is the connector's handle on the grant — the invite link on Telegram — and is null before anything was issued. A failed grant carries failure_kind (unreachable, not_permitted, target_missing, rate_limited, configuration, transient, other) and failure_detail.
How it fails
RESOURCE_NOT_FOUNDsubscription_id is not a valid UUID, or the subscription belongs to another team or a project outside the token's scope.
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-subscription:view.
How is this guide?
Last updated on
get_subscription
One subscription by UUID — plan, subscriber, payment method, status, price, trial and end dates, and whether it was cancelled. Read it before acting on it.
pause_subscription
Pause an active or trialing subscription — billing stops and the member keeps their place. The reversible alternative to cancelling.