Connect Recurly to ChatGPT: Manage Subscriptions & Billing Cycles

If your team needs to give a Large Language Model (LLM) read and write access to your billing infrastructure, you need a Model Context Protocol (MCP) server. You can either spend weeks building a custom translation layer between ChatGPT and Recurly, or use a managed integration platform to generate a secure MCP URL instantly. If your team uses Claude instead of ChatGPT, check out our guide on connecting Recurly to Claude, or explore our broader overview on connecting Recurly to AI Agents.

Giving an AI agent access to billing data is high-stakes engineering. A hallucinated parameter on a POST request can accidentally refund thousands of dollars, or worse, permanently delete an account's billing history. You need strict schema validation, deterministic routing, and a predictable way for the LLM to understand what an endpoint actually does.

This guide breaks down exactly how to use Truto to dynamically generate a secure, authenticated MCP server for Recurly, connect it natively to ChatGPT, and execute complex billing workflows using natural language.

The Engineering Reality of the Recurly API

A custom MCP server is a self-hosted integration layer that translates an LLM's JSON-RPC tool calls into REST API requests. If you build this yourself, you own the entire integration lifecycle. Recurly's API has specific architectural constraints that break generic CRUD assumptions. If you don't account for these, your AI agent will fail silently or behave unpredictably.

Strict State Machines on Invoices and Subscriptions You cannot simply "delete" a subscription or "void" an invoice without checking its state. Recurly enforces strict state transitions. For example, you can only void a credit invoice (not a charge invoice), and only if it is not in a closed or processing state. Subscriptions can be canceled, terminated, or paused - each with completely different financial implications. If your MCP server doesn't expose these specific methods with strict JSON schemas, the LLM will guess the payload format and fail validation.

Cursor-Based Pagination When an LLM requests a list of accounts or transactions, Recurly returns a paginated list using cursor-based headers. LLMs are notoriously bad at handling pagination spontaneously. Your MCP server must explicitly inject limit and next_cursor properties into the query schema, along with a system prompt instructing the LLM to pass the cursor value back unchanged. Without this, the model will try to ingest 10,000 invoices in a single turn and crash the context window.

Leaky Bucket Rate Limits Recurly enforces strict API rate limits. When you hit the limit, Recurly returns an HTTP 429 Too Many Requests. It is critical to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When Recurly returns a 429, Truto passes that error directly to the caller and normalizes the rate limit info into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). Your MCP client or agent framework is entirely responsible for reading these headers and executing exponential backoff.

Creating the Recurly MCP Server

Instead of writing custom JSON-RPC wrappers for every Recurly endpoint, Truto generates tools dynamically based on the underlying integration's documentation records. If an endpoint lacks a documentation record, it is entirely omitted from the MCP server. This acts as a strict quality gate, ensuring the LLM only sees curated, AI-ready operations.

You can generate an MCP server for Recurly in two ways.

Method 1: Via the Truto UI

1. Log into your Truto dashboard and navigate to the integrated account page for your Recurly connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., limit methods to read only, or scope by specific tags).
5. Copy the generated secure MCP server URL.

Method 2: Via the API

For teams managing AI infrastructure programmatically, you can generate the MCP server via a POST request. The API validates the configuration, generates a secure token, stores a hashed version in Cloudflare KV, and returns the URL.

POST https://api.truto.one/integrated-account/<recurly-account-id>/mcp
Authorization: Bearer <your-truto-api-token>
Content-Type: application/json
 
{
  "name": "Recurly Billing Agent MCP",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["billing", "subscriptions"]
  },
  "expires_at": "2026-12-31T23:59:59Z"
}

The response contains the URL you will feed to ChatGPT:

{
  "id": "abc-123",
  "name": "Recurly Billing Agent MCP",
  "config": { "methods": ["read", "write", "custom"] },
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to ChatGPT

Once you have the Truto MCP URL, you must register it with ChatGPT. The URL contains a cryptographic token that fully authenticates the request to the specific Recurly tenant.

Option A: Via the ChatGPT UI

If you are using ChatGPT Plus, Team, or Enterprise, you can add the server directly via the interface:

1. In ChatGPT, navigate to Settings -> Apps -> Advanced settings.
2. Enable Developer mode.
3. Under MCP servers / Custom connectors, click Add new server.
4. Name: Recurly MCP
5. Server URL: Paste the https://api.truto.one/mcp/... URL.
6. Save. ChatGPT will immediately perform a handshake, call the tools/list endpoint, and ingest the Recurly tools.

Option B: Via Manual Config File

If you are running a custom MCP client, Claude Desktop, or a local agent framework, you can map the URL using the standard Server-Sent Events (SSE) transport wrapper provided by the MCP spec.

{
  "mcpServers": {
    "recurly": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

Hero Tools for Recurly

When ChatGPT connects, Truto dynamically derives snake_case tool names, query schemas, and body schemas from the Recurly documentation records. Here are the highest-leverage tools available for billing operations.

list_all_recurly_accounts

Retrieves a paginated list of accounts. This is heavily utilized as a lookup step, allowing the LLM to resolve an email address to a Recurly id or code before executing a write operation.

"Find the Recurly account ID for user contact@example.com and tell me if they have a past_due invoice."

recurly_accounts_list_subscriptions

Lists all subscriptions tied to a specific account ID. Crucial for auditing a customer's active plans, trial end dates, and current billing cycle status.

"List all active subscriptions for account ID 98765. What is the current period end date for their primary plan?"

create_a_recurly_subscription

Provisions a new subscription for an account. Requires strict adherence to the body schema, including plan_code, account, and currency.

"Create a new subscription for account ID 12345 using plan_code 'pro-monthly-2026' in USD."

recurly_subscriptions_cancel

Cancels a subscription. Recurly continues the subscription through the current billing cycle before expiring it. This is the safest way to offboard a user without issuing immediate prorated refunds.

"Cancel the subscription with ID sub_abc123. Confirm the exact date it will expire."

get_single_recurly_invoice_by_id

Fetches the complete state of a specific invoice, including line items, subtotal, tax, and discount arrays. Required for investigating billing disputes.

"Pull the details for invoice ID inv_998877. How much was applied in taxes, and what was the net term?"

recurly_invoice_refunds_refund

Executes a refund against an invoice. Can process full refunds, percentage refunds, or line-item specific refunds depending on the payload passed by the LLM.

"Issue a 50% partial refund for invoice ID inv_445566 and note it as a service disruption concession."

recurly_invoice_apply_credit_balances_apply_credit_balance

Applies any available credit from an account's credit invoices to the outstanding balance of a pending or past-due charge invoice.

"Check if account ID 12345 has any available credit, and if so, apply it to their past due invoice inv_777777."

For the complete inventory of available operations, schemas, and return types, view the Recurly integration page.

Workflows in Action

When connected via MCP, ChatGPT handles complex API orchestration autonomously. The LLM determines the execution order, parses the JSON output from one tool, and maps it into the parameters of the next tool.

Scenario 1: Automated Churn Mitigation

A support agent asks ChatGPT to cancel a user's subscription and verify when their access should be revoked.

"Cancel the primary subscription for support@acmecorp.com and tell me exactly when their account access should be shut off."

Execution Steps:

1. list_all_recurly_accounts: The LLM queries email=support@acmecorp.com to retrieve the Recurly account_id.
2. recurly_accounts_list_subscriptions: The LLM queries the account_id to find the active subscription and extracts the subscription_id.
3. recurly_subscriptions_cancel: The LLM executes the cancellation endpoint using the subscription_id.

Outcome: The LLM reads the current_period_ends_at property from the cancellation response and informs the user: "The subscription has been successfully canceled. It will remain active until the end of the current billing cycle on October 31st, 2026, at which point access should be revoked."

sequenceDiagram
    participant User as Support Agent
    participant GPT as ChatGPT
    participant MCP as Truto MCP Server
    participant API as Recurly API

    User->>GPT: Cancel sub for support@acmecorp.com
    GPT->>MCP: call list_all_recurly_accounts
    MCP->>API: GET /accounts?email=support@acmecorp.com
    API-->>MCP: Returns Account ID (12345)
    MCP-->>GPT: JSON Account Object
    GPT->>MCP: call recurly_accounts_list_subscriptions (account_id: 12345)
    MCP->>API: GET /accounts/12345/subscriptions
    API-->>MCP: Returns Subscription ID (sub_999)
    MCP-->>GPT: JSON Subscription Object
    GPT->>MCP: call recurly_subscriptions_cancel (subscription_id: sub_999)
    MCP->>API: PUT /subscriptions/sub_999/cancel
    API-->>MCP: Returns 200 OK + updated state
    MCP-->>GPT: JSON response
    GPT-->>User: Subscription canceled. Expires Oct 31.

Scenario 2: Investigating and Refunding a Dispute

A finance admin asks the LLM to investigate a high-value customer and issue a partial refund for an SLA breach.

"Find the most recent paid invoice for account ID 55667. We breached our SLA. Refund exactly $500 from that invoice."

Execution Steps:

1. list_all_recurly_account_invoices: The LLM fetches the invoice history for account 55667, filtering for state=paid.
2. get_single_recurly_invoice_by_id: The LLM pulls the specific invoice to verify the refundable_amount is greater than $500.
3. recurly_invoice_refunds_refund: The LLM crafts the refund payload, specifying the amount and targeting the invoice ID.

Outcome: The LLM confirms the refund execution and returns the ID of the newly generated credit invoice for the finance team's records.

Security and Access Control

Exposing your billing system to an LLM requires zero-trust architecture. Truto's MCP servers provide strict, token-level access controls to limit the blast radius of AI operations.

• Method Filtering: Set config.methods = ["read"] during server generation. The server will dynamically strip all create, update, and delete tools. The LLM can read invoice data but cannot physically alter subscriptions or issue refunds.
• Tag Filtering: Integration resources in Truto are grouped by tags. By specifying config.tags = ["subscriptions"], the MCP server will only expose subscription endpoints, hiding overarching ledger or general ledger tools.
• API Token Authentication: Setting require_api_token_auth: true forces the MCP client to pass a valid Truto API token in the Authorization header. This prevents unauthorized access even if the MCP URL is leaked.
• Ephemeral Tokens: Use the expires_at field to create temporary MCP servers. If you only want to grant an automated workflow access for 24 hours, the Durable Object alarm will automatically purge the credentials and KV entries when the TTL expires.

Strategic Wrap-Up

Connecting ChatGPT to Recurly via an MCP server turns a conversational UI into a fully autonomous billing operator. Instead of manually digging through Recurly dashboards to find invoice IDs, resolve cursors, and build refund payloads, your team can state their intent in plain English and let the agent handle the orchestration.

By leveraging a managed infrastructure layer, you bypass the boilerplate of OAuth token management, dynamic JSON schema generation, and strict proxy routing. You define the access boundaries, and the LLM safely executes the logic.