Connect Recharge to Claude: Automate Orders, Bundles, and Credits

If your e-commerce or customer success teams need to connect Recharge to Claude to automate subscription modifications, manage store credit, or troubleshoot payment failures, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and the Recharge REST API. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on /connect-recharge-to-chatgpt-manage-recurring-billing-and-customers/ or explore our broader architectural overview on /connect-recharge-to-ai-agents-orchestrate-subscription-lifecycles/.

Giving a Large Language Model (LLM) read and write access to a complex recurring billing engine like Recharge is an engineering challenge. You have to handle API token lifecycles, map nested JSON schemas to MCP tool definitions, and deal with Recharge's strict state machines. Every time the API updates, you have to update your server code, redeploy, and test the integration.

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

The Engineering Reality of the Recharge API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against a specialized billing platform is painful. Recharge is built to manage complex subscription lifecycles, and its API reflects that complexity. If you build a custom MCP server, you will face specific integration hurdles.

The Subscription Cascade State Machine

Recharge does not use a flat data model. It relies on a cascading state machine where Subscriptions generate Charges, which in turn generate Orders. If an LLM attempts to modify an upcoming delivery by simply editing an Order object, those changes will likely be overwritten when the next Charge processes.

To skip a delivery, the agent cannot just delete an order. It must call specific procedural endpoints like recharge_charges_skip and pass exactly the correct subscription_ids and future dates. A managed MCP server exposes these procedural actions as strict, strongly typed tools, preventing the LLM from making invalid state changes.

Asynchronous Batch Processing

When managing large catalogs or applying discounts across thousands of subscriptions, the standard synchronous API endpoints will time out. Recharge requires you to use its Async Batch API.

Building this for an LLM is tricky because LLMs struggle with polling loops. You have to expose tools to create_a_recharge_async_batch, submit it via recharge_async_batches_process, and then provide a way for the agent to check get_single_recharge_async_batch_by_id. The MCP server must define clear schemas for the batch_type payload so the agent knows exactly what JSON to inject into the batch tasks.

Rate Limits and 429 Handling

Recharge enforces strict API rate limits to protect its infrastructure. A common misconception in agent engineering is that the integration proxy should silently absorb and retry rate limits.

Truto takes a different approach: it does not retry, throttle, or apply backoff on rate limit errors. When the upstream Recharge API returns an HTTP 429 Too Many Requests error, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. This explicit pass-through ensures your AI agent or MCP client has complete visibility into its quota consumption and can apply intelligent, context-aware backoff strategies rather than hanging blindly on a proxy connection.

Step 1: Generate the Recharge MCP Server

Rather than hand-coding tool definitions, Truto derives them dynamically from the integration's resource definitions and documentation. Every available endpoint is automatically transformed into an MCP-compatible JSON-RPC tool.

You can generate the MCP server URL using either the Truto UI or the API.

Method 1: Via the Truto UI

For teams who prefer visual configuration, you can generate a server directly from the dashboard:

1. Log into your Truto dashboard and navigate to the integrated account page for your connected Recharge store.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., name the server, filter to only allow "read" and "write" methods, set an optional expiration date).
5. Click Save and copy the generated MCP server URL (it will look like https://api.truto.one/mcp/abc123def456...).

Method 2: Via the Truto API

For dynamic agent orchestration, you can generate the MCP server programmatically. The API validates that the integration has tools available, generates a secure cryptographic token, stores it in distributed KV storage, and returns a ready-to-use URL.

// POST /integrated-account/:id/mcp
const response = await fetch('https://api.truto.one/integrated-account/YOUR_RECHARGE_ACCOUNT_ID/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TRUTO_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Claude Recharge Billing Assistant",
    config: {
      methods: ["read", "write", "custom"] // Allow all CRUD + custom actions
    }
  })
});
 
const mcpServer = await response.json();
console.log(mcpServer.url); // Pass this URL to Claude

Step 2: Connect the MCP Server to Claude

Once you have the Truto MCP URL, connecting it to Claude requires zero additional coding. The URL encodes the specific integrated account and tool filters, making it a fully self-contained configuration.

Method A: Via the Claude Desktop UI

If you are using Claude Desktop:

1. Open Claude Desktop and navigate to Settings -> Integrations.
2. Click Add MCP Server.
3. Give your server a recognizable name (e.g., "Recharge Billing Engine").
4. Paste the Truto MCP URL into the connection field.
5. Click Add. Claude will instantly connect, perform an initialization handshake, and discover all available Recharge tools.

Method B: Via Manual Config File

If you prefer to configure Claude Desktop manually or are managing configurations across a team, you can edit the claude_desktop_config.json file directly.

Open your configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows) and add the server using the SSE transport model:

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

Restart Claude Desktop. The agent is now ready to manage subscriptions and orders.

High-Leverage Recharge MCP Tools

Truto automatically generates tools for the entire Recharge API. For AI agents, the most valuable tools are those that handle complex operational workflows, billing adjustments, and customer support interventions.

Here are the critical tools to expose to Claude:

1. list_all_recharge_subscriptions

Retrieves a filtered list of subscriptions. Essential for support agents looking up a customer's active recurring items before making changes.

"Find all active subscriptions for the customer with ID 987654321 and tell me their next scheduled charge dates."

2. recharge_subscriptions_cancel

Safely cancels an active subscription. Requires a cancellation reason, which the LLM can extract from a customer support ticket or conversation.

"Cancel subscription 112233. The customer emailed us saying they are moving and don't need coffee deliveries anymore. Use 'Customer Moving' as the cancellation reason."

3. recharge_charges_skip

Skips a specific charge and reschedules its associated subscriptions to a future date. This is much safer than manipulating raw dates on the subscription object itself.

"The customer asked to skip their upcoming delivery on charge ID 554433. Skip it and reschedule the associated subscriptions to next month."

4. recharge_charges_add_free_gift

Appends a free gift to an upcoming queued charge. Perfect for retention workflows where an agent detects customer frustration and wants to offer a proactive appeasement.

"Add external variant ID 99887766 (our free tote bag) as a free gift to the queued charge ID 445566 for customer 123123."

5. create_a_recharge_credit_account

Creates a standalone store credit account for a customer, which they can use against future subscription charges. Requires initial value and currency definitions.

"Create a store credit account for customer 998877. Give them an initial balance of $25.00 USD to apologize for the delayed shipping on their last order."

6. recharge_charges_refund

Executes a full or partial refund against a specific processed charge. The agent must parse the original charge total to ensure they do not exceed the refundable amount.

"Issue a partial refund of $10.00 on charge 556677. The customer reported that one of the bags of coffee arrived torn."

Note: This is only a curated selection of high-leverage tools. The Truto MCP server provides access to the complete API surface. View the full inventory and schema details on the Recharge integration page.

Workflows in Action

Giving Claude access to these tools transforms it from a passive chat interface into an autonomous e-commerce operations engine. Here is how specific personas can use natural language to execute complex Recharge workflows.

Scenario 1: Customer Success Handling a Churn Risk

When a high-value subscriber emails support to complain about product fatigue and mentions they might cancel, the support agent can use Claude to intervene instantly.

"Look up the active subscriptions for customer 887766. If they have an upcoming charge next week, skip it so they have a break. Then, add the free sample pack (variant ID 332211) to their next active charge as a surprise gift."

Step-by-step execution:

1. Claude calls list_all_recharge_subscriptions to identify the customer's active items and next charge date.
2. Claude identifies the specific charge ID associated with next week's delivery.
3. Claude calls recharge_charges_skip to push the billing cycle back.
4. Claude calls recharge_charges_add_free_gift on the newly scheduled charge, passing the sample pack variant ID.

sequenceDiagram
    participant User as CS Rep
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Recharge as Recharge API

    User->>Claude: "Skip next charge, add free gift for customer 887766"
    Claude->>MCP: Call list_all_recharge_subscriptions(customer_id: 887766)
    MCP->>Recharge: GET /subscriptions
    Recharge-->>MCP: Subscription & Charge Data
    MCP-->>Claude: JSON response
    
    Claude->>MCP: Call recharge_charges_skip(charge_id: 12345)
    MCP->>Recharge: POST /charges/12345/skip
    Recharge-->>MCP: Success
    MCP-->>Claude: Charge skipped

    Claude->>MCP: Call recharge_charges_add_free_gift(charge_id: 12345, variant: 332211)
    MCP->>Recharge: POST /charges/12345/free_gifts
    Recharge-->>MCP: Gift added
    MCP-->>Claude: Success
    Claude-->>User: "Done. The charge is skipped and the free gift is queued."

Scenario 2: E-Commerce Ops Issuing Store Credit

A logistics failure resulted in a late delivery for a VIP customer. The operations manager wants to apologize with store credit rather than a direct cash refund to encourage future retention.

"Customer 445566 had a delayed shipment on their last order. Please create a new credit account for them with a $50.00 USD balance to use on future subscription renewals."

Step-by-step execution:

1. Claude parses the request to identify the customer ID and the desired credit amount.
2. Claude calls create_a_recharge_credit_account, formatting the payload to specify customer_id: 445566, initial_value: 50.00, and type: "store_credit".
3. The tool executes, and Claude returns the new credit account ID and confirmation to the operations manager.

Security and Access Control

Exposing an e-commerce billing engine to an LLM requires strict security guardrails. Truto MCP servers provide multiple layers of configuration to limit the blast radius of AI agents:

• Method Filtering: Restrict servers to specific operations via config.methods. You can create a read-only server (["read"]), a server that only allows specific actions (["list", "get"]), or one that allows modifications (["write"]).
• Tag Filtering: Limit the server to specific resource groups. For example, pass config.tags: ["orders", "customers"] to expose those tools while hiding the webhooks or platform configuration tools.
• Require API Token Auth: By setting require_api_token_auth: true, possession of the MCP URL alone is not enough. The client (e.g., Claude) must also pass a valid Truto API token in the headers, adding a secondary layer of enterprise authentication.
• Time-to-Live (Expires At): Generate short-lived MCP servers for contractors, automated CI/CD tests, or temporary AI agents by setting an ISO datetime on the expires_at field. Cloudflare KV and internal Durable Objects will automatically purge the server upon expiration.

Moving Beyond Manual Workflows

Connecting Recharge to Claude via an MCP server replaces brittle script maintenance with fluid, natural language orchestration. You no longer have to write custom scripts to skip charges, apply bulk discounts, or issue store credits. By wrapping the entire Recharge REST API in a standardized toolset, your operations teams can resolve complex billing scenarios in seconds.

Stop writing point-to-point integration code for your AI agents. Let Truto handle the OAuth tokens, dynamic tool generation, and security boundaries, so you can focus on building intelligent e-commerce workflows.