# MCP tool reference 1 callable tools. Use tools/call at https://mcp.schedulerzero.com/mcp with the exact tool name and arguments below. The /tools/ paths in this view are documentation identifiers, not HTTP endpoints. Request execution is disabled for this reference. Inputs are shown for personal API keys (bound) and for OAuth/delegated agents. Output schemas describe MCP structuredContent: native objects pass through; arrays, scalars and null use a data wrapper. Text content retains the native JSON result. [Connect a client](/mcp/connect) · [Authentication and authorization](/authentication) · [Generated auth guide](/auth.md) · [Download tool catalog](/mcp-catalog.json) · [Agent documentation](/llms.txt) ## manage_subscription Start a plan purchase, plan change, or payment-method update and hand a person the Stripe-hosted page that completes it. Use when a person wants to upgrade, switch billing cycle, or fix a failed payment. Return the `url` to them and poll the subscription until the change lands. Nothing is charged until the person completes the hosted page; never ask for card details. A frozen Organization can still use this — it is the way out. Return the authorization or checkout handoff to the person. The agent may initiate and inspect status, but must not complete the human approval. Scopes: billing:manage, billing:read Risk: costly; confirmation: human_completion; idempotency: supported. ### Input schema (personal API key) ```json { "type": "object", "properties": { "organizationId": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$", "format": "uuid" }, "action": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "change_plan" ] }, "request": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "starter", "growth", "pro" ] }, "billingCycle": { "type": "string", "enum": [ "monthly", "annual" ] }, "successUrl": { "$ref": "#/$defs/HttpUrl" }, "cancelUrl": { "$ref": "#/$defs/HttpUrl" }, "returnUrl": { "$ref": "#/$defs/HttpUrl" } }, "required": [ "plan", "successUrl", "cancelUrl" ], "patternProperties": { "^(?!(?:plan|billingCycle|successUrl|cancelUrl|returnUrl)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "plan", "billingCycle", "successUrl", "cancelUrl", "returnUrl" ] } } }, "required": [ "kind", "request" ], "patternProperties": { "^(?!(?:kind|request)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "kind", "request" ] } }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "update_payment_method" ] }, "request": { "type": "object", "properties": { "returnUrl": { "$ref": "#/$defs/HttpUrl" } }, "required": [ "returnUrl" ], "patternProperties": { "^(?!(?:returnUrl)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "anyOf": [ { "type": "string", "enum": [ "returnUrl" ] } ] } } }, "required": [ "kind", "request" ], "patternProperties": { "^(?!(?:kind|request)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "kind", "request" ] } } ] } }, "required": [ "organizationId", "action" ], "patternProperties": { "^(?!(?:organizationId|action)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "organizationId", "action" ] }, "$defs": { "HttpUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^https?:\\/\\/[^\\s/$.?#][^\\s]*$" } } } ``` ### Input schema (OAuth / delegated agent) ```json { "type": "object", "properties": { "organizationId": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$", "format": "uuid" }, "action": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "change_plan" ] }, "request": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "starter", "growth", "pro" ] }, "billingCycle": { "type": "string", "enum": [ "monthly", "annual" ] }, "successUrl": { "$ref": "#/$defs/HttpUrl" }, "cancelUrl": { "$ref": "#/$defs/HttpUrl" }, "returnUrl": { "$ref": "#/$defs/HttpUrl" } }, "required": [ "plan", "successUrl", "cancelUrl" ], "patternProperties": { "^(?!(?:plan|billingCycle|successUrl|cancelUrl|returnUrl)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "plan", "billingCycle", "successUrl", "cancelUrl", "returnUrl" ] } } }, "required": [ "kind", "request" ], "patternProperties": { "^(?!(?:kind|request)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "kind", "request" ] } }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "update_payment_method" ] }, "request": { "type": "object", "properties": { "returnUrl": { "$ref": "#/$defs/HttpUrl" } }, "required": [ "returnUrl" ], "patternProperties": { "^(?!(?:returnUrl)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "anyOf": [ { "type": "string", "enum": [ "returnUrl" ] } ] } } }, "required": [ "kind", "request" ], "patternProperties": { "^(?!(?:kind|request)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "kind", "request" ] } } ] } }, "required": [ "organizationId", "action" ], "patternProperties": { "^(?!(?:organizationId|action)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "organizationId", "action" ] }, "$defs": { "HttpUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^https?:\\/\\/[^\\s/$.?#][^\\s]*$" } } } ``` ### Output schema (structuredContent) ```json { "$defs": { "HttpUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^https?:\\/\\/[^\\s/$.?#][^\\s]*$" }, "UtcDateTimeEncoded": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "ProviderId": { "type": "string", "minLength": 1, "maxLength": 512 } }, "type": "object", "anyOf": [ { "allOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "checkout", "portal" ] }, "url": { "$ref": "#/$defs/HttpUrl" } }, "required": [ "kind", "url" ], "patternProperties": { "^(?!(?:kind|url)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "kind", "url" ] } }, { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$", "format": "uuid" }, "plan": { "type": "string", "enum": [ "trial", "starter", "growth", "pro" ] }, "status": { "type": "string", "enum": [ "incomplete", "incomplete_expired", "trialing", "active", "past_due", "canceled", "unpaid", "paused", "frozen" ] }, "billingCycle": { "anyOf": [ { "type": "string", "enum": [ "monthly", "annual" ] }, { "type": "null" } ] }, "seats": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "trialStart": { "anyOf": [ { "$ref": "#/$defs/UtcDateTimeEncoded" }, { "type": "null" } ] }, "trialEnd": { "anyOf": [ { "$ref": "#/$defs/UtcDateTimeEncoded" }, { "type": "null" } ] }, "periodStart": { "anyOf": [ { "$ref": "#/$defs/UtcDateTimeEncoded" }, { "type": "null" } ] }, "periodEnd": { "anyOf": [ { "$ref": "#/$defs/UtcDateTimeEncoded" }, { "type": "null" } ] }, "cancelAtPeriodEnd": { "type": "boolean" }, "pastDueSince": { "anyOf": [ { "$ref": "#/$defs/UtcDateTimeEncoded" }, { "type": "null" } ] }, "stripeCustomerId": { "anyOf": [ { "$ref": "#/$defs/ProviderId" }, { "type": "null" } ] }, "stripeSubscriptionId": { "anyOf": [ { "$ref": "#/$defs/ProviderId" }, { "type": "null" } ] }, "priceId": { "anyOf": [ { "$ref": "#/$defs/ProviderId" }, { "type": "null" } ] }, "frozen": { "type": "boolean" }, "limits": { "anyOf": [ { "type": "object", "properties": { "maxEmailsPerMonth": { "type": "integer", "minimum": -1 }, "maxInboxes": { "type": "integer", "minimum": -1 }, "maxCampaigns": { "type": "integer", "minimum": -1 }, "maxContactsPerCampaign": { "type": "integer", "minimum": -1 }, "whiteLabelEnabled": { "type": "boolean" }, "prioritySupport": { "type": "boolean" }, "warmupPoolTier": { "type": "string", "enum": [ "standard", "premium" ] }, "maxWarmupEmailsPerDay": { "type": "integer", "minimum": -1 }, "maxWarmupInboxes": { "type": "integer", "minimum": -1 }, "privatePoolEnabled": { "type": "boolean" }, "dedicatedEgressEnabled": { "type": "boolean" }, "maxActiveEgressIps": { "type": "integer", "minimum": -1 }, "egressInfrastructureBudgetCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byokEnabled": { "type": "boolean" }, "fullMailboxSyncEnabled": { "type": "boolean" } }, "required": [ "maxEmailsPerMonth", "maxInboxes", "maxCampaigns", "maxContactsPerCampaign", "whiteLabelEnabled", "prioritySupport", "warmupPoolTier", "maxWarmupEmailsPerDay", "maxWarmupInboxes", "privatePoolEnabled", "dedicatedEgressEnabled", "maxActiveEgressIps", "egressInfrastructureBudgetCents", "byokEnabled", "fullMailboxSyncEnabled" ], "patternProperties": { "^(?!(?:maxEmailsPerMonth|maxInboxes|maxCampaigns|maxContactsPerCampaign|whiteLabelEnabled|prioritySupport|warmupPoolTier|maxWarmupEmailsPerDay|maxWarmupInboxes|privatePoolEnabled|dedicatedEgressEnabled|maxActiveEgressIps|egressInfrastructureBudgetCents|byokEnabled|fullMailboxSyncEnabled)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "maxEmailsPerMonth", "maxInboxes", "maxCampaigns", "maxContactsPerCampaign", "whiteLabelEnabled", "prioritySupport", "warmupPoolTier", "maxWarmupEmailsPerDay", "maxWarmupInboxes", "privatePoolEnabled", "dedicatedEgressEnabled", "maxActiveEgressIps", "egressInfrastructureBudgetCents", "byokEnabled", "fullMailboxSyncEnabled" ] } }, { "type": "null" } ] } }, "required": [ "id", "plan", "status", "billingCycle", "seats", "trialStart", "trialEnd", "periodStart", "periodEnd", "cancelAtPeriodEnd", "pastDueSince", "stripeCustomerId", "stripeSubscriptionId", "priceId", "frozen", "limits" ], "patternProperties": { "^(?!(?:id|plan|status|billingCycle|seats|trialStart|trialEnd|periodStart|periodEnd|cancelAtPeriodEnd|pastDueSince|stripeCustomerId|stripeSubscriptionId|priceId|frozen|limits)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "id", "plan", "status", "billingCycle", "seats", "trialStart", "trialEnd", "periodStart", "periodEnd", "cancelAtPeriodEnd", "pastDueSince", "stripeCustomerId", "stripeSubscriptionId", "priceId", "frozen", "limits" ] } }, "maxItems": 20 } }, "required": [ "subscriptions" ], "patternProperties": { "^(?!(?:subscriptions)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "anyOf": [ { "type": "string", "enum": [ "subscriptions" ] } ] } } ] }, { "type": "object" } ] }, { "type": "object", "properties": { "data": { "allOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "checkout", "portal" ] }, "url": { "$ref": "#/$defs/HttpUrl" } }, "required": [ "kind", "url" ], "patternProperties": { "^(?!(?:kind|url)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "kind", "url" ] } }, { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$", "format": "uuid" }, "plan": { "type": "string", "enum": [ "trial", "starter", "growth", "pro" ] }, "status": { "type": "string", "enum": [ "incomplete", "incomplete_expired", "trialing", "active", "past_due", "canceled", "unpaid", "paused", "frozen" ] }, "billingCycle": { "anyOf": [ { "type": "string", "enum": [ "monthly", "annual" ] }, { "type": "null" } ] }, "seats": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "trialStart": { "anyOf": [ { "$ref": "#/$defs/UtcDateTimeEncoded" }, { "type": "null" } ] }, "trialEnd": { "anyOf": [ { "$ref": "#/$defs/UtcDateTimeEncoded" }, { "type": "null" } ] }, "periodStart": { "anyOf": [ { "$ref": "#/$defs/UtcDateTimeEncoded" }, { "type": "null" } ] }, "periodEnd": { "anyOf": [ { "$ref": "#/$defs/UtcDateTimeEncoded" }, { "type": "null" } ] }, "cancelAtPeriodEnd": { "type": "boolean" }, "pastDueSince": { "anyOf": [ { "$ref": "#/$defs/UtcDateTimeEncoded" }, { "type": "null" } ] }, "stripeCustomerId": { "anyOf": [ { "$ref": "#/$defs/ProviderId" }, { "type": "null" } ] }, "stripeSubscriptionId": { "anyOf": [ { "$ref": "#/$defs/ProviderId" }, { "type": "null" } ] }, "priceId": { "anyOf": [ { "$ref": "#/$defs/ProviderId" }, { "type": "null" } ] }, "frozen": { "type": "boolean" }, "limits": { "anyOf": [ { "type": "object", "properties": { "maxEmailsPerMonth": { "type": "integer", "minimum": -1 }, "maxInboxes": { "type": "integer", "minimum": -1 }, "maxCampaigns": { "type": "integer", "minimum": -1 }, "maxContactsPerCampaign": { "type": "integer", "minimum": -1 }, "whiteLabelEnabled": { "type": "boolean" }, "prioritySupport": { "type": "boolean" }, "warmupPoolTier": { "type": "string", "enum": [ "standard", "premium" ] }, "maxWarmupEmailsPerDay": { "type": "integer", "minimum": -1 }, "maxWarmupInboxes": { "type": "integer", "minimum": -1 }, "privatePoolEnabled": { "type": "boolean" }, "dedicatedEgressEnabled": { "type": "boolean" }, "maxActiveEgressIps": { "type": "integer", "minimum": -1 }, "egressInfrastructureBudgetCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byokEnabled": { "type": "boolean" }, "fullMailboxSyncEnabled": { "type": "boolean" } }, "required": [ "maxEmailsPerMonth", "maxInboxes", "maxCampaigns", "maxContactsPerCampaign", "whiteLabelEnabled", "prioritySupport", "warmupPoolTier", "maxWarmupEmailsPerDay", "maxWarmupInboxes", "privatePoolEnabled", "dedicatedEgressEnabled", "maxActiveEgressIps", "egressInfrastructureBudgetCents", "byokEnabled", "fullMailboxSyncEnabled" ], "patternProperties": { "^(?!(?:maxEmailsPerMonth|maxInboxes|maxCampaigns|maxContactsPerCampaign|whiteLabelEnabled|prioritySupport|warmupPoolTier|maxWarmupEmailsPerDay|maxWarmupInboxes|privatePoolEnabled|dedicatedEgressEnabled|maxActiveEgressIps|egressInfrastructureBudgetCents|byokEnabled|fullMailboxSyncEnabled)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "maxEmailsPerMonth", "maxInboxes", "maxCampaigns", "maxContactsPerCampaign", "whiteLabelEnabled", "prioritySupport", "warmupPoolTier", "maxWarmupEmailsPerDay", "maxWarmupInboxes", "privatePoolEnabled", "dedicatedEgressEnabled", "maxActiveEgressIps", "egressInfrastructureBudgetCents", "byokEnabled", "fullMailboxSyncEnabled" ] } }, { "type": "null" } ] } }, "required": [ "id", "plan", "status", "billingCycle", "seats", "trialStart", "trialEnd", "periodStart", "periodEnd", "cancelAtPeriodEnd", "pastDueSince", "stripeCustomerId", "stripeSubscriptionId", "priceId", "frozen", "limits" ], "patternProperties": { "^(?!(?:id|plan|status|billingCycle|seats|trialStart|trialEnd|periodStart|periodEnd|cancelAtPeriodEnd|pastDueSince|stripeCustomerId|stripeSubscriptionId|priceId|frozen|limits)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "type": "string", "enum": [ "id", "plan", "status", "billingCycle", "seats", "trialStart", "trialEnd", "periodStart", "periodEnd", "cancelAtPeriodEnd", "pastDueSince", "stripeCustomerId", "stripeSubscriptionId", "priceId", "frozen", "limits" ] } }, "maxItems": 20 } }, "required": [ "subscriptions" ], "patternProperties": { "^(?!(?:subscriptions)$)[\\s\\S]*$": false }, "additionalProperties": true, "propertyNames": { "anyOf": [ { "type": "string", "enum": [ "subscriptions" ] } ] } } ] }, { "not": { "type": "object" } } ] } }, "required": [ "data" ], "additionalProperties": false } ] } ``` ### Underlying API operations - `billing.getSubscription`: `GET /v1/organizations/:organizationId/billing/subscription` - `billing.upgrade`: `POST /v1/organizations/:organizationId/billing/upgrade` - `billing.billingPortal`: `POST /v1/organizations/:organizationId/billing/portal`