Connect Recurly to Claude: Automate Invoices & Ledger Tracking

If you need to connect Recurly to Claude to automate subscription management, investigate failed payments, or audit general ledger accounts, you need a Model Context Protocol (MCP) server. This infrastructure layer acts as the bridge translating Claude's natural language tool calls into Recurly's complex REST APIs. You can spend weeks building and maintaining this bridge yourself, or you can use a managed platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Recurly to ChatGPT or explore our architectural overview on connecting Recurly to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sensitive billing engine like Recurly is a massive engineering undertaking. You have to navigate rigid state machines, map deeply nested catalog schemas to LLM tool definitions, and enforce strict execution policies. Every time Recurly updates an endpoint, you have to patch your integration code.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Recurly, connect it natively to Claude, and execute complex billing workflows.

The Engineering Reality of the Recurly API

A custom MCP server is a self-hosted integration layer that sits between the LLM and the vendor API. While the open MCP standard provides a predictable way for models like Claude 3.5 Sonnet to discover tools, implementing it against Recurly's API introduces distinct challenges.

If you build a custom MCP server for Recurly, you own the entire integration lifecycle. Here is exactly what makes the Recurly API uniquely difficult to wrap for AI agents:

Rigid State Machine Constraints Recurly enforces a strict state machine for core billing objects. An invoice moves linearly through pending, processing, past_due, failed, successful, and closed. You cannot simply send an "update" payload to void an invoice. If Claude decides an invoice needs to be voided, the MCP server must expose specific endpoints (like recurly_invoice_voids_void) and the LLM must understand the prerequisite state (it cannot be processing or closed). Building an MCP server requires writing defensive logic to ensure the LLM understands these state boundaries before making destructive calls.

Complex Nested Subscriptions and Line Items Recurly's data model heavily nests line items, add-ons, and tax details within subscriptions and invoices. Extracting these into flat, callable JSON schemas that an LLM can understand without hallucinating structure is tedious. If an LLM attempts to issue a partial refund targeting a specific line item, it must accurately pass the nested UUIDs back into the payload.

Strict Rate Limits and Header Normalization Recurly enforces concurrent rate limits that vary heavily by endpoint. If an AI agent attempts to run a bulk audit of past-due accounts in a loop, it will rapidly hit a 429 Too Many Requests error. If your custom MCP server fails silently, the LLM hallucinates the workflow's completion. Truto takes a precise approach here: it does not absorb or automatically retry rate limit errors. Instead, when Recurly returns a 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. This shifts the responsibility of backoff execution to the caller, ensuring the LLM or orchestration layer retains full visibility into quota exhaustion.

graph TD
  Claude["Claude Desktop / Custom Agent"] -->|"JSON-RPC via SSE"| TrutoMCP["Truto Managed MCP Server"]
  TrutoMCP -->|"Schema extraction & Auth injection"| Proxy["Truto Proxy API"]
  Proxy -->|"REST"| Recurly["Recurly API"]
  Recurly -->|"HTTP 429 Too Many Requests"| Proxy
  Proxy -->|"IETF Rate Limit Headers"| TrutoMCP
  TrutoMCP -->|"Error Payload with Backoff Data"| Claude

How to Generate a Recurly MCP Server with Truto

Truto eliminates the need to build custom translation layers by dynamically generating MCP tools from Recurly's underlying resource documentation and JSON schemas. A tool only appears in the MCP server if it has a documented endpoint, acting as a strict quality gate for the AI.

You can generate the MCP server URL in two ways.

Method 1: Via the Truto UI

This is the fastest method for internal operational teams providing tools to analysts.

1. Navigate to the Integrated Accounts page in the Truto dashboard.
2. Select your connected Recurly account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read methods only, or tag filter for invoices).
6. Copy the secure generated MCP server URL.

Method 2: Via the API

For platform engineers embedding AI tools programmatically, use the Truto API to generate short-lived, tightly scoped MCP servers.

Make an authenticated POST request to /integrated-account/:id/mcp:

const response = await fetch('https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TRUTO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Recurly FinOps Agent",
    config: {
      methods: ["read", "custom"], // Excludes write operations like create/delete
      tags: ["invoices", "ledger"]
    },
    expires_at: "2026-12-31T23:59:59Z"
  })
});
 
const mcpServer = await response.json();
console.log(mcpServer.url); // e.g. https://api.truto.one/mcp/a1b2c3d4e5f6...

The returned URL contains a cryptographic token that securely maps to the Recurly integrated account. No further OAuth configuration is required on the client.

Connecting the Recurly MCP Server to Claude

Once you have your Truto MCP URL, you can connect it to Claude. You can do this through the user interface or by directly editing the configuration file.

Method A: Via the Claude UI

1. Open Claude Settings.
2. Navigate to the Integrations or Connectors tab.
3. Click Add MCP Server (or Add Custom Connector).
4. Paste the URL generated by Truto.
5. Click Add.

Claude will immediately hit the /mcp/:token endpoint, initialize the JSON-RPC handshake, and dynamically pull the Recurly schemas.

Method B: Via the Configuration File

For automated deployments or advanced local testing with Claude Desktop, you can manually inject the server using the standard MCP configuration file format. You will use the @modelcontextprotocol/server-sse transport to connect directly to Truto's HTTPS endpoint.

Edit your claude_desktop_config.json:

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

Restart Claude Desktop. The model will now have native capability to invoke Recurly tools.

6 Hero Tools for Recurly Workflows

Truto exposes dozens of tools for Recurly, standardizing flat namespaces for query and body parameters. Here are six high-leverage tools that unlock complex AI automation.

Find Recurly Accounts

The list_all_recurly_accounts tool allows Claude to query your subscriber base. It supports powerful server-side filtering by email, subscriber status, or past-due state, which prevents the LLM from pulling excessive payloads.

"Find the Recurly account associated with billing@acmecorp.com. I need their account ID and current subscription status."

Inspect Subscriptions

Using the recurly_accounts_list_subscriptions tool, Claude can pull the active, cancelled, or paused subscriptions for a specific user. This is crucial for verifying service tiers before processing downgrades.

"List all active subscriptions for account ID 'acme-1234'. Show me the current term dates and the underlying plan code."

Audit Invoices

The list_all_recurly_invoices tool is the backbone of revenue operations. Claude can use this to filter for failed or past-due invoices over a specific date range, extracting total balances and tax line items.

"Find all past_due invoices for account 'acme-1234' generated in the last 30 days. Summarize the subtotal, taxes, and total outstanding balance."

Execute Refunds

When a dispute occurs, Claude can execute financial operations via the recurly_invoice_refunds_refund tool. Because this is a destructive action, ensure you use Truto's method filtering if you only want read-only agents.

"Issue a full refund for invoice ID 'inv-987654321'. Ensure the refund amount maps precisely to the original charge."

Manage Subscription Cancellations

The recurly_subscriptions_cancel tool gracefully terminates a subscription. The LLM understands that Recurly will keep the subscription active until the end of the current billing cycle, setting it to expire natively.

"Cancel the subscription ID 'sub-abc123xyz'. Confirm the date it will fully expire based on the current billing cycle."

Audit the General Ledger

The list_all_recurly_general_ledger_accounts tool enables Claude to act as a localized ERP assistant, pulling liability and revenue GL accounts configured in Recurly to help cross-reference data against systems like NetSuite or QuickBooks.

"Retrieve all general ledger accounts configured in Recurly. List their IDs, descriptions, and account types so I can map them for reconciliation."

For the complete schema definitions and full API capability list, view the Recurly integration page.

Workflows in Action

When you combine an LLM's reasoning engine with normalized tool schemas, you can execute multi-step operational logic without writing custom scripts.

Scenario 1: The FinOps Refund Investigation

Persona: Finance Operations Lead

"A customer (billing@acmecorp.com) complained they were charged after they asked to cancel. Find their account, check if they have an active subscription, locate the most recent paid invoice, cancel the subscription, and issue a full refund for that invoice."

Execution Steps:

1. Claude calls list_all_recurly_accounts with the query parameter email=billing@acmecorp.com to extract the id.
2. Claude calls recurly_accounts_list_subscriptions using the account ID to verify the active plan.
3. Claude calls recurly_subscriptions_cancel to terminate future renewals.
4. Claude calls list_all_recurly_invoices filtering for state=paid to locate the target transaction.
5. Claude executes recurly_invoice_refunds_refund passing the invoice ID.

Output: The LLM returns a detailed timeline confirming the subscription has been cancelled (noting the exact expiration date) and provides the newly generated credit invoice ID proving the refund was successful.

Scenario 2: Resolving a Past-Due Account

Persona: Billing Support Agent

"Account 'startup-xyz' is complaining about service interruption. Check if they have past-due invoices. If they do, check if they have any active coupon redemptions or credit balances that should have covered it."

Execution Steps:

1. Claude calls list_all_recurly_invoices filtering by account_id=startup-xyz and state=past_due.
2. Claude identifies the outstanding balance.
3. Claude calls list_all_recurly_account_balances to check for available credit.
4. Claude calls list_all_recurly_coupon_redemptions_actives to verify if a promotional discount dropped off prematurely.

Output: Claude summarizes the billing state: "Account 'startup-xyz' has a past-due balance of $450 on invoice #1042. They have $0 in available credit, and their 50% off coupon expired last week, which is why the invoice spiked and failed on their card."

Security and Access Control

Exposing an enterprise billing engine to an LLM requires strict boundary controls. Truto enforces zero-trust architecture at the MCP layer, ensuring you never over-provision access to AI agents.

• Method Filtering: Limit your MCP server to read-only operations by passing methods: ["read"]. This allows Claude to call list_all_recurly_invoices but strictly blocks create_a_recurly_purchase.
• Tag Filtering: Group tools by functional area. Pass tags: ["ledger"] to build a server that can strictly audit GL accounts and nothing else.
• Extra Authentication (require_api_token_auth): For shared environments, enable this flag to require the connecting client to pass a valid Truto API token in the Authorization header, preventing unauthorized execution even if the MCP URL is leaked.
• Expiration (expires_at): Automate lifecycle management by defining a TTL. The MCP token and its configuration are automatically purged from the distributed key-value store precisely at expiration, killing all agent access instantly.

Architecting for Scale

Connecting Claude to Recurly via custom integration code is an exercise in chasing moving targets. Every time the billing schema shifts or pagination logic updates, your AI agent breaks.

By leveraging Truto's documentation-driven MCP generation, you decouple the agent's capability from the underlying API's friction. Your workflows remain resilient, your rate limit handling becomes predictable, and your engineering team avoids writing hundreds of lines of boilerplate schema mapping.

Stop hand-coding REST to JSON-RPC translation layers. Start building autonomous billing agents.