paddle-mcp

Docs

How to connect paddle-mcp to your AI agent.

1. Sign in and add your Paddle key

  1. Create an account with email + password, magic link, or Google.
  2. On the dashboard, paste your Paddle API key for sandbox and/or production.

Get your Paddle keys at vendors.paddle.com (production) or sandbox-vendors.paddle.com (sandbox). The minimum scope required is read/write on the resources you want to expose.

2. Connect a client

paddle-mcp speaks Streamable HTTP MCP transport with OAuth 2.1 — any MCP-compatible client works. Setup for the popular ones:

Claude Code

claude mcp add --scope user --transport http paddle-mcp \
  https://paddle-mcp.3vlbn.com/mcp

Then run /mcp in Claude Code, pick paddle-mcp, and click Authenticate.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "paddle-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://paddle-mcp.3vlbn.com/mcp"]
    }
  }
}

Cursor

Settings → MCP → Add Server → HTTP → https://paddle-mcp.3vlbn.com/mcp.

Other MCP-compatible clients

3. Try a tool

Ask the agent in plain language — the tools have rich descriptions and the agent picks the right one. Some examples that work out of the box:

Example 1 — refund a customer

Find Paddle customer alice@example.com in production, list their
last 3 transactions, and refund the most recent past_due one with
reason "duplicate charge".

Agent chains list_customers → list_transactions → create_adjustment. The refund tool returns a dry-run preview first; you confirm before money moves.

Example 2 — stand up a new pricing plan end-to-end

In production, create a product "Team Plan" (SaaS tax category), then
add a $49/mo and $490/yr USD price on it, and finally a 20%-off launch
coupon WELCOME20 restricted to those two prices, expiring in 90 days.

Agent chains create_product → 2× create_price → create_discount.

Example 3 — test your webhook flow without a real card

Create a Paddle simulation webhook destination pointing at
https://my-app.example.com/webhook, then fire the subscription_cancellation
scenario at it and tell me the response status from my server.

Agent chains create_notification_setting (with traffic_source: "simulation") → list_simulation_types → create_simulation → run_simulation → list_simulation_runs.

Example 4 — preview a plan upgrade before charging

For alice@example.com's active subscription, show me exactly what
would be charged if I move her to the Pro monthly plan today, with
proration immediate. Don't actually change anything.

Agent chains find_customer → list_subscriptions → preview_subscription_update. You see proration math + next-invoice impact; nothing in Paddle changes.

Example 5 — answer a "what happened?" support ticket

Customer bob@example.com emailed that his subscription disappeared.
Find him, list everything that happened on his account in the last
14 days, and generate a customer portal link so he can self-serve.

Agent chains find_customer → list_events (filtered) → create_customer_portal_session. One conversation closes the ticket.

Example 6 — quote international pricing

How much would the Team Plan ($49/mo + $490/yr) cost a customer in
Germany with VAT applied? Show me the formatted totals in EUR.

Agent calls preview_pricing with the basket and customer_ip_address or an address_id. Returns net, VAT, total in EUR with formatted strings, no checkout created.

Example 7 — rename a product and bump its description

Find the "Pro Plan" product, change its name to "Pro Team" and update
the description to mention SSO + audit log. Don't touch any prices.

Agent chains list_products → update_product. Updates apply immediately to invoices and the customer portal; existing subscriptions keep their billing cycle.

Example 8 — extend a coupon's lifetime

The launch coupon WELCOME20 is about to expire. Bump its
expires_at to end of next quarter and double the usage_limit.

Agent chains list_discounts (find by code) → update_discount. Already-applied discounts on subscriptions stay applied; only future redemptions see the new rules.

Tool reference

39 tools across 14 Paddle resources. Each tool description tells the agent when to use it and what id formats to expect (pro_, pri_, ctm_, sub_, txn_, adj_, dsc_, ntfset_, ntf_, ntfsim_, evt_, rep_, cpls_).

Read (22)

Write (17)

All "confirm-required" tools return a dry-run preview unless called with confirmed: true. The agent will show you the preview before re-issuing the call. Preview tools (preview_subscription_update, preview_pricing) never touch state and don't need confirmation.

Plans & quotas

Every plan unlocks every tool — the only difference is the monthly call quota. Failed calls (validation errors, Paddle 4xx, missing key) don't count.

Need help?

Email support@3vlbn.com.