Paddle MCP server

The Paddle MCP server lets AI agents interact with your Paddle account. Instead of navigating the dashboard or making API calls, you can ask an agent in natural language to handle pricing, billing, support, and integration workflows.

How it works

The Paddle MCP server connects AI agents to your Paddle account so they can:

• Build and evolve your pricing model, including regional pricing and migrations.
• Investigate failed payments and resolve billing issues.
• Generate reports and analyze revenue, refunds, and transaction patterns.
• Process subscription upgrades, downgrades, pauses, and cancellations.
• Onboard enterprise customers with custom pricing and manual invoicing.
• Generate integration code, configure webhooks, and simulate events for testing.

Available tools

The Paddle MCP server exposes the full Paddle API, so your agent can perform any action you can perform using the API.

You scope the tools available to the agent at install time using the --tools flag:

We recommend starting with read-only or non-destructive while you get comfortable with the server, then widen as needed.

Before you begin

Create an API key with the permissions needed for the tools you plan to use.

Install the MCP server

The server uses stdio transport and runs locally. Setup varies slightly across clients.

{
  "mcpServers": {
    "paddle": {
      "command": "npx",
      "args": [
        "-y",
        "@paddle/paddle-mcp",
        "--api-key=YOUR_API_KEY",
        "--environment=sandbox",
        "--tools=non-destructive"
      ]
    }
  }
}

claude mcp add paddle -- npx -y @paddle/paddle-mcp --api-key=YOUR_API_KEY --environment=sandbox --tools=non-destructive

codex mcp add paddle npx -y @paddle/paddle-mcp --api-key=YOUR_API_KEY --environment=sandbox --tools=non-destructive

{
  "mcpServers": {
    "paddle": {
      "command": "npx",
      "args": [
        "-y",
        "@paddle/paddle-mcp",
        "--api-key=YOUR_API_KEY",
        "--environment=sandbox",
        "--tools=non-destructive"
      ]
    }
  }
}

npx -y @paddle/paddle-mcp --api-key=YOUR_API_KEY --environment=sandbox --tools=non-destructive

Use the server

Once installed, tools are registered and available for the agent to use. Some clients prompt before running each tool.

Example prompts

Use these example prompts to get started.

Manage your pricing

Describe your pricing structure to the agent — tiers, billing cycles, trial periods, regional overrides — and let it create the products and prices. For migrations, walk through old plans, grandfather pricing, and archiving the old catalog step by step.

Set up three subscription plans for my collaboration SaaS: Basic at $29/mo or $290/yr (14-day trial), Pro at $79/mo or $790/yr (14-day trial), Advanced at $299/mo or $2,990/yr (14-day trial). Also add a seats add-on at $10/seat/month or $100/seat/year, quantity 1-1000. After you create everything, show me the products and prices in a markdown table.

Debug and resolve billing issues

Give the agent a customer email or ID, a time range, and the issue to investigate. It can check subscription history, payment attempts, adjustments, and scheduled changes, then recommend or execute a fix.

Investigate the failed payment for sarah@example.com. Think step-by-step: when it failed, whether it's recurring, what plan they're on, whether there are scheduled changes, and details of the payment method. If you find multiple failures, check whether other subscriptions for this customer show the same pattern.

Understand company performance

Ask the agent to generate a report and analyze it. Reports arrive as CSV files — the agent can retrieve them with the get_report_csv tool once ready.

Generate a transaction_line_items report for the past 6 months, filtered for completed and canceled statuses across all currencies. Identify our three highest- and lowest-revenue product/price combinations, flag pricing anomalies across regions, and recommend adjustments.

Handle subscription and lifecycle changes

For upgrades, downgrades, pauses, or cancellations, always ask for a preview first (preview_subscription_update) so you see the financial impact before the change is applied.

Customer john@startup.com wants to upgrade from Basic ($29/mo) to Pro ($79/mo) immediately. Preview the change, show me the current and new amounts plus any proration, then wait for my approval before executing.

Onboard enterprise customers

Paste the quote or contract details, include tax ID and billing contacts, and ask the agent to create custom pricing, configure manual invoicing, and preview the first invoice before execution.

Set up Example Inc. as an enterprise customer: 100 licenses at $45/user/month billed annually in USD, plus a $6,000/year Premium Support flat fee. Billing contact bob@example.com, tax ID 12-3456789, address 123 Business Park, New York, NY 10001. Preview the full transaction before creating anything.

Integrate and test Paddle

Use the agent to scaffold integration code, configure notification destinations, and simulate webhook events end to end.

Create a notification destination for my Next.js webhook endpoint at https://example.com/api/webhooks, subscribed to subscription.created, subscription.updated, and transaction.completed. Then simulate a subscription.created event so I can verify my handler.

Best practices

• Mention Paddle explicitly. "Find a customer in Paddle" is less ambiguous than "find a customer."
• Provide all the context. Customer IDs, time ranges, currencies — pass them in rather than letting the agent guess.
• Ask for a plan first. For complex work, get the agent to draft a plan before executing. Approve or edit, then run.
• State your goal. Tell the agent what success looks like and what format you want the output in.
• Iterate.
  If the first response misses, refine the prompt rather than starting over.