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.
Read a subscription's current state back rather than assuming it. Every subscription write tool —
cancel_subscription,
pause_subscription,
unpause_subscription,
reactivate_subscription,
remind_pass_holder — refuses a subscription in the wrong state,
and this is how an agent finds out which state it is in first. The fields are the ones the REST
subscription payload carries.
`canceled` and `ends_at` together tell the story
A subscription cancelled at period end has canceled: true and an ends_at
still in the future — the member keeps access until then, and
reactivate_subscription can still call the cancellation off. Once ends_at
has passed there is nothing to reactivate.
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 to fetch.
What it returns
{ "data": { "id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4", "plan_id": "9b7c2e15-4d63-4f80-a2b1-7e5d0c9f3a46", "subscriber_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80", "method_id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63", "payment_status": "active", "payment_price": "12.00", "currency_id": "0f6c3b2a-8e19-4d57-b4a2-1c9e7d5f3a80", "trial_ends_at": null, "ends_at": "2026-10-06T10:05:00+00:00", "canceled": false, "compensation_seconds": 0, "redeemed_at": null, "created_at": "2026-09-06T10:05:00+00:00", "updated_at": "2026-09-06T10:05:00+00:00", "grants": [] }}compensation_seconds is the outage time Outage Compensation banked on the purchase; ends_at already includes it, so on a recurring plan the gateway's renewal is ends_at minus compensation_seconds.
grants lists the access grants the subscription holds, one row per resource and dated window, in the shape list_subscription_grants documents.
payment_price is a decimal string in the plan's currency; parse it as a decimal, not a float.
redeemed_at is set only for a subscription that came from an access code, and method_id is null
for those.
How it fails
RESOURCE_NOT_FOUNDunknown subscription_id, or a subscription 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
cancel_subscription
Queue a subscription cancellation. Provider-side cancellation and local state mutation run asynchronously on the webhooks queue.
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.