Connect Paddle to Claude: Track Revenue and Reporting Metrics

If you need to connect Paddle to Claude to track monthly recurring revenue (MRR), automate subscription management, issue refunds, or pull financial reports, you need a Model Context Protocol (MCP) server. This server acts as the secure translation layer between Claude's tool calls and Paddle's billing APIs. 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 connecting Paddle to ChatGPT or explore our broader architectural overview on connecting Paddle to AI Agents.

Giving a Large Language Model (LLM) read and write access to a Merchant of Record (MoR) platform like Paddle is a significant engineering challenge. You must handle complex entity relationships, strict tax compliance validations, and pagination across massive transaction datasets. Every time Paddle updates a billing endpoint or introduces a new pricing capability, you must 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 Paddle, connect it natively to Claude Desktop, and execute complex revenue operations using natural language.

The Engineering Reality of the Paddle 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 and compliance API is painful. Paddle operates as a Merchant of Record, meaning it takes on global tax liabilities and compliance burdens. Its API reflects this strict regulatory environment.

If you decide to build a custom Paddle MCP server, here are the specific integration challenges you will face:

Strict Relational Dependencies for Compliance In standard SaaS APIs, creating a transaction is often a flat API call. In Paddle, a transaction is deeply relational. To create a valid transaction, you must resolve the exact price_id linked to a product_id. If the transaction involves a specific customer, it must reference a customer_id, which in turn requires a strictly validated address_id. For example, Paddle enforces mandatory postal codes for specific regions (like US ZIP codes and UK postcodes) to calculate accurate local taxes. An LLM cannot simply guess this payload structure. A managed MCP server exposes tools with strictly defined JSON schemas that explicitly guide the LLM to traverse this relationship tree.

Immutability of Financial Records Paddle enforces strict accounting principles. You cannot simply "delete" a billed transaction. If a customer needs their money back, you cannot send a DELETE request to a transaction endpoint. Instead, you must invoke complex operations like creating an adjustment to issue a refund or credit against a specific transaction item. Building an MCP server requires mapping these domain-specific operations into discrete, understandable tools for the LLM, rather than blindly exposing raw CRUD operations.

Explicit Rate Limit Handling Without Magic Retries Like any enterprise platform, Paddle enforces rate limits. When integrating via Truto, it is critical to understand how these limits are processed. Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Paddle API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller.

Instead of obscuring the failure, Truto normalizes the upstream rate limit information into standardized headers per the IETF specification:

• ratelimit-limit: The total number of requests allowed in the current window.
• ratelimit-remaining: The number of requests remaining.
• ratelimit-reset: The time when the rate limit window resets.

The calling agent or client is entirely responsible for reading these headers and implementing its own retry or backoff logic. Truto does not automatically absorb rate limit errors, ensuring your agent has deterministic control over execution pacing.

Generating a Managed MCP Server for Paddle

Truto's MCP architecture derives tool definitions dynamically from the integration's documented API schemas. Rather than hand-coding tool definitions, Truto generates them on the fly based on the connected integration.

Each MCP server is scoped to a single integrated account and secured via a cryptographic token in the URL. You can create this server either through the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For ad-hoc agent setups and quick testing, the UI is the fastest path:

1. Log into your Truto dashboard and navigate to the integrated account page for your connected Paddle instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can optionally filter the available tools by HTTP method (e.g., read-only operations) or specific tool tags.
5. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For production workflows, you will likely provision MCP servers programmatically for your end users. You can do this by sending an authenticated POST request to the Truto API.

Endpoint: POST /integrated-account/:id/mcp

Request Body Example:

{
  "name": "Paddle Revenue Agent MCP",
  "config": {
    "methods": ["read", "write", "custom"]
  },
  "expires_at": null
}

The API will validate the configuration, generate a secure, hashed token in Cloudflare KV, and return the ready-to-use URL:

{
  "id": "mcp-789-xyz",
  "name": "Paddle Revenue Agent MCP",
  "config": {
    "methods": ["read", "write", "custom"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Connecting the MCP Server to Claude

Once you have your Truto MCP server URL, you must register it with your Claude environment.

Method A: Via the Claude UI (Enterprise / Team)

If you are using Claude for Work (Team or Enterprise plans), organization owners can add the server directly via the interface:

1. In Claude, navigate to Settings -> Integrations -> Add MCP Server.
2. Paste your Truto MCP server URL into the configuration.
3. Click Add.

Claude will immediately connect, perform the JSON-RPC initialization handshake, and parse the available Paddle tools.

Method B: Via the Claude Desktop Configuration File

For local development or individual Claude Desktop users, you map the server via the claude_desktop_config.json file. Truto provides an SSE (Server-Sent Events) bridge that makes it simple to connect remote URLs to local desktop clients.

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

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

Restart Claude Desktop. Look for the hammer icon in the input bar to verify the tools have loaded successfully.

Hero Tools for Paddle Operations

Truto exposes the entirety of the Paddle API, but certain operations are particularly high-leverage for AI agents handling revenue operations. Here are the core hero tools your agent will rely on.

get_single_paddle_subscription_by_id

This tool retrieves the complete entity for a specific subscription, including its current status, the customer it belongs to, billing cycles, and detailed line items.

Contextual Usage Notes: This is almost always the first step in any customer success or billing modification workflow. The agent must fetch the current state to understand what products the user has before attempting to pause, update, or cancel.

"Pull the complete subscription details for subscription ID sub_01h8k... and summarize their current billing cycle and next payment date."

update_a_paddle_subscription_by_id

This tool allows the agent to modify a subscription without replacing it. It can change line items, adjust the next billing date, or apply specific settings.

Contextual Usage Notes: When altering items or billing dates, the agent must include the proration_billing_mode parameter to explicitly declare how Paddle should handle the financial difference. Omitted items are automatically removed from the subscription.

"Update subscription sub_01h8k... to add the new Enterprise Support price ID pri_01h9j... and set the proration billing mode to prorated_immediately."

list_all_paddle_transactions

This tool lists transactions across your account. It is the backbone of custom reporting and order tracking.

Contextual Usage Notes: The agent can use extensive query filters here, including status, customer, origin, and date ranges. The returned payload includes deep details containing calculated totals, tax rates, and collection modes.

"Find all completed transactions for customer ID cst_01xyz... from the last 30 days and calculate the total amount they were billed."

create_a_paddle_adjustment

This tool creates an adjustment to refund or credit one or more items on a billed transaction.

Contextual Usage Notes: Because Paddle is an MoR, you cannot simply delete a payment. You must specify an action, a reason, and the specific transaction_id. In live environments, these adjustments are often created with a pending_approval status until reviewed by Paddle compliance teams.

"Create an adjustment to issue a full refund for transaction ID txn_01h8j... because the customer reported the digital download link was broken."

paddle_subscriptions_pause

This tool pauses an active subscription, preventing future billing until resumed.

Contextual Usage Notes: By default, the pause takes effect at the end of the current billing period. The agent can set effective_from to immediately if an abrupt halt is required.

"Pause the subscription sub_01h8k... immediately and confirm the new subscription status."

create_a_paddle_discount

This tool creates a new discount code that can be applied to checkouts or subscriptions.

Contextual Usage Notes: The agent must define the description, type (flat or percentage), and amount. This is highly effective for retention workflows where an agent attempts to save a churning customer by generating a custom code.

"Create a 20 percent discount code named 'Retention Offer' valid for the next 7 days, and give me the code to send to the customer."

list_all_paddle_metrics_monthly_recurring_revenues

This tool extracts Paddle's core Monthly Recurring Revenue (MRR) metrics as a daily timeseries for a specified date range.

Contextual Usage Notes: Essential for financial analysis. The agent must provide distinct from and to dates. It returns the timeseries array alongside the primary currency code.

"Pull the MRR metrics for the period of January 1st to January 31st and generate a brief summary of revenue growth."

To view the complete inventory of available tools, required parameters, and detailed JSON schemas, visit the Truto Paddle Integration Page.

Workflows in Action

With the MCP server connected, Claude can now chain these API tools together to execute multi-step revenue workflows.

Scenario 1: Handling a Refund and Churn Request

When a customer requests a refund and wishes to cancel their service, support teams normally have to log into the Paddle dashboard, track down the transaction, issue the adjustment, find the linked subscription, and cancel it. Claude handles this autonomously.

"Customer cst_01xyz requested a cancellation and a refund for their latest charge. Please issue a refund for their most recent transaction and cancel their active subscription immediately."

Execution Steps:

1. Claude calls list_all_paddle_transactions filtered by customer_id and sorted by date to find the most recent transaction_id.
2. Claude calls create_a_paddle_adjustment using that transaction_id, setting the action to refund with a customer request reason.
3. Claude calls list_all_paddle_subscriptions filtered by the same customer_id to locate the active subscription_id.
4. Claude calls paddle_subscriptions_cancel with effective_from set to immediately.

Outcome: The customer is fully refunded and their subscription is terminated. Claude outputs a clear summary of the transaction ID adjusted and the subscription ID canceled.

Scenario 2: Churn Prevention via Targeted Discounts

If a customer signals they are leaving due to cost, an agent can pause their billing to stop the clock and dynamically generate a retention discount.

"The customer on subscription sub_01h8k... is complaining about the price. Pause their subscription at the end of the billing cycle and generate a 25% off discount code we can offer them to resume."

sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Paddle as Paddle API

    User->>Claude: "Pause subscription sub_123 and create a 25% discount"
    Claude->>Truto: Call paddle_subscriptions_pause (effective: end_of_billing_period)
    Truto->>Paddle: POST /subscriptions/sub_123/pause
    Paddle-->>Truto: 200 OK (Status Updated)
    Truto-->>Claude: Result: status paused
    Claude->>Truto: Call create_a_paddle_discount
    Truto->>Paddle: POST /discounts (amount: 25, type: percentage)
    Paddle-->>Truto: 200 OK (Discount Created)
    Truto-->>Claude: Result: code SAVE25
    Claude-->>User: "Subscription scheduled to pause. Retention code SAVE25 generated."

Outcome: The subscription is successfully set to pause, preventing an unwanted renewal charge, and Claude provides the newly generated discount code to be passed to the user.

Scenario 3: Generating Financial Reports

Executives frequently need quick snapshots of financial health without writing complex SQL queries against a data warehouse.

"Pull the MRR metrics and the active subscriber metrics for Q3 (July 1 to September 30) and summarize the month-over-month growth trends."

Execution Steps:

1. Claude calls list_all_paddle_metrics_monthly_recurring_revenues with from set to July 1 and to set to September 30.
2. Claude calls list_all_paddle_metrics_active_subscribers for the same date range.
3. Claude analyzes the timeseries data arrays returned by both endpoints.

Outcome: Claude generates a plain-text financial brief highlighting the starting MRR, ending MRR, net subscriber additions, and percentage growth across the quarter based on raw MoR data.

Security and Access Control

When giving an LLM access to a live billing system, security configuration is paramount. Truto's MCP servers provide granular controls to limit agent blast radius:

• Method Filtering: Use the config.methods array during creation to strictly enforce read-only access (e.g., ["read"]). This ensures the agent can query metrics and subscriptions but physically cannot issue refunds or alter prices.
• Tag Filtering: Use config.tags to limit the agent to specific functional areas. For instance, filtering by a reporting tag restricts the agent to analytics and metrics endpoints while obscuring customer PII operations.
• Secondary Authentication: Enable require_api_token_auth: true to force the client to pass a valid Truto API token in the headers. This ensures possession of the MCP URL alone is useless without active developer credentials.
• Time-To-Live (TTL): Set an expires_at ISO datetime when generating the server. Truto's backend infrastructure automatically drops the token and schedules a hard cleanup alarm, ensuring temporary reporting agents don't leave permanent backdoors into your revenue data.

Architecting for Scale

Connecting Paddle to Claude requires strict adherence to schema design, compliance rules, and API lifecycle management. Relying on auto-generated, documentation-driven MCP servers eliminates the need to manually update JSON-RPC handlers every time Paddle adjusts a parameter or introduces a new API version. By offloading the translation layer to Truto, your engineering team can focus on orchestrating the actual AI workflows - like automated churn prevention and financial analysis - rather than maintaining bespoke API boilerplate.