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 is a remote, hosted MCP server. Your agent connects to it over HTTPS using your Paddle API key as a Bearer token, then it 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.

Paddle hosts an MCP server for each environment:

Sandbox API keys (prefixed pdl_sdbx_) only authenticate against the sandbox URL. Live keys only authenticate against the live URL. A mismatch surfaces as an authentication failure.

Codemode

The Paddle MCP server uses a codemode interface. This means instead of exposing every Paddle API operation as a separate MCP tool, the server exposes three tools that together cover the full API:

A typical workflow looks like this:

• The agent calls search to confirm the method name and parameter shape.
• The agent then calls execute with code that chains the relevant API calls.
• Result is returned to the agent.

Codemode works because agents are better at writing code to call tools than at calling tools directly. Research shows it results in 60% faster execution, 68% fewer tokens, and 88% fewer API round trips while maintaining equal accuracy.

As a user of the MCP server, you don't need to do anything differently. The server handles the codemode interface for you.

Permissions and destructive actions

The Paddle MCP server doesn't gate destructive operations on its own. You control what the agent can do by scoping the Paddle API key you connect with.

• Hard scoping: Create an API key with only the permissions the agent needs. Start with read-only permissions while you're evaluating, then widen as you build confidence.
• Soft warnings: Destructive operations are flagged with a destructiveHint annotation, and the server attaches a warning field to the corresponding execute response. There's no guarantee agents will follow the warning, so you should always review each execute before it runs.
• Client-side approval: We recommend enabling "ask permission" mode in your MCP client so you see and approve each execute before it runs.

Before you begin

Create an API key with the permissions needed for the work you want the agent to do. Sandbox keys are prefixed pdl_sdbx_.

Install the MCP server

The Paddle MCP server runs remotely. We recommend adding both environments under separate server names: paddle-sandbox and paddle-live. This means that your agent can route prompts to the right environment, and help you port data from one environment to the other.

claude mcp add --transport http paddle-sandbox https://sandbox-mcp.paddle.com/mcp --header "Authorization: Bearer SANDBOX_API_KEY"

claude mcp add --transport http paddle-live https://mcp.paddle.com/mcp --header "Authorization: Bearer LIVE_API_KEY"

{
  "mcpServers": {
    "paddle-sandbox": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://sandbox-mcp.paddle.com/mcp",
        "--header",
        "Authorization: Bearer SANDBOX_API_KEY"
      ]
    },
    "paddle-live": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.paddle.com/mcp",
        "--header",
        "Authorization: Bearer LIVE_API_KEY"
      ]
    }
  }
}

codex mcp add paddle-sandbox --url https://sandbox-mcp.paddle.com/mcp --bearer-token-env-var SANDBOX_API_KEY

codex mcp add paddle-live --url https://mcp.paddle.com/mcp --bearer-token-env-var LIVE_API_KEY

{
  "mcpServers": {
    "paddle-sandbox": {
      "type": "http",
      "url": "https://sandbox-mcp.paddle.com/mcp",
      "headers": {
        "Authorization": "Bearer SANDBOX_API_KEY"
      }
    },
    "paddle-live": {
      "type": "http",
      "url": "https://mcp.paddle.com/mcp",
      "headers": {
        "Authorization": "Bearer LIVE_API_KEY"
      }
    }
  }
}

{
 "servers": {
  "paddle-live": {
   "type": "http",
   "url": "https://mcp.paddle.com/mcp",
   "headers": {
    "Authorization": "Bearer LIVE_API_KEY"
   }
  },
  "paddle-sandbox": {
      "type": "http",
   "url": "https://sandbox-mcp.paddle.com/mcp",
   "headers": {
    "Authorization": "Bearer SANDBOX_API_KEY"
   }
  }
 },
 "inputs": []
}

{
  "mcpServers": {
    "paddle-sandbox": {
      "type": "http",
      "url": "https://sandbox-mcp.paddle.com/mcp",
      "headers": {
        "Authorization": "Bearer SANDBOX_API_KEY"
      }
    },
    "paddle-live": {
      "type": "http",
      "url": "https://mcp.paddle.com/mcp",
      "headers": {
        "Authorization": "Bearer LIVE_API_KEY"
      }
    }
  }
}

npx -y mcp-remote https://sandbox-mcp.paddle.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

Use the server

Once installed, the agent sees two parallel toolsets for sandbox and live. Be explicit in your prompts about which environment you mean: "create a product in sandbox" routes to paddle-sandbox, "create the equivalent product in live" routes to paddle-live.

Example prompts

Use these example prompts to get started. Mention paddle-sandbox or paddle-live explicitly so the agent picks the right toolset.

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.

Using paddle-sandbox, 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.

Using paddle-live, 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 once ready.

Using paddle-live, 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 so you see the financial impact before the change is applied.

Using paddle-live, 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.

Using paddle-live, 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.

Using paddle-sandbox, 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."
• Name the environment.
  Prefix prompts with "Using paddle-sandbox" or "Using paddle-live" so the agent routes to the right toolset.
• 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.