> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt). # Paddle MCP server Give AI agents access to your Paddle account so they can read data and take actions across pricing, billing, and integration workflows. --- 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. {% callout type="warning" title="AI agents can make mistakes" %} The Paddle MCP server has access to the data in your account. Review every action the agent takes before and after execution. {% /callout %} ## 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](https://developer.paddle.com/sdks/sandbox.md): | Environment | URL | | ----------- | ------------------------------------------------------------- | | Sandbox | `https://sandbox-mcp.paddle.com/mcp` | | Live | `https://mcp.paddle.com/mcp` | 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. {% callout type="note" %} The Paddle MCP server lets your agent take actions in your account. To give your agent up-to-date knowledge of Paddle, set up the [docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp.md). {% /callout %} ## Codemode The Paddle MCP server uses [a codemode interface](https://blog.cloudflare.com/code-mode/). 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: | Tool | What it does | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `search` | Looks up Paddle API methods by name or description. Returns the method path, parameters, and response shape so the agent knows how to call it. | | `execute` | Runs a JavaScript async function that chains one or more Paddle API calls in a single invocation. Variables don't persist between calls. | | `report_missing_tool` | Lets the agent flag a missing capability so we can prioritize it. This doesn't call the Paddle API, it reports the missing tool to the Paddle team. | 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](https://github.com/imran31415/codemode_python_benchmark) 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](https://developer.paddle.com/api-reference/about/authentication.md) with only the [permissions](https://developer.paddle.com/api-reference/about/permissions.md) 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. {% callout type="warning" %} Agents in "auto" mode make their own judgement call about whether to execute an operation annotated as destructive based on the intent of your prompt and the context of the conversation. {% /callout %} ## Before you begin [Create an API key](https://developer.paddle.com/api-reference/about/authentication.md) with the [permissions](https://developer.paddle.com/api-reference/about/permissions.md) 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. {% tabs sync="vibe-coding-tool" %} {% tab-item title="Claude Code" %} {% callout type="note" %} Install the Claude Code plugin to add the Paddle MCP servers and skills to your project in one command. See [Build with Claude Code](https://developer.paddle.com/get-started/ai/claude-code.md) {% /callout %} Run these commands, replacing `SANDBOX_API_KEY` and `LIVE_API_KEY` with the matching sandbox or live key: ```bash {% title="Sandbox" %} claude mcp add --transport http paddle-sandbox https://sandbox-mcp.paddle.com/mcp --header "Authorization: Bearer SANDBOX_API_KEY" ``` ```bash {% title="Live" %} claude mcp add --transport http paddle-live https://mcp.paddle.com/mcp --header "Authorization: Bearer LIVE_API_KEY" ``` {% /tab-item %} {% tab-item title="Claude Desktop" %} 1. Open Claude Desktop and go to **Settings > Developer > Edit Config**. 2. Add the `paddle-sandbox` and `paddle-live` servers to the `mcpServers` object. Claude Desktop doesn't support remote HTTP transport natively, so we proxy through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). 3. Replace `SANDBOX_API_KEY` and `LIVE_API_KEY` with your sandbox and live keys. 4. Save the file and restart Claude Desktop. ```json {% title="claude_desktop_config.json" %} { "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" ] } } } ``` {% /tab-item %} {% tab-item title="Codex" %} Run these commands, replacing `SANDBOX_API_KEY` and `LIVE_API_KEY` with the matching sandbox or live key: ```bash {% title="Sandbox" %} codex mcp add paddle-sandbox --url https://sandbox-mcp.paddle.com/mcp --bearer-token-env-var SANDBOX_API_KEY ``` ```bash {% title="Live" %} codex mcp add paddle-live --url https://mcp.paddle.com/mcp --bearer-token-env-var LIVE_API_KEY ``` {% /tab-item %} {% tab-item title="Cursor" %} ### One-click install [Install the Paddle MCP (sandbox) in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=paddle-sandbox&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vc2FuZGJveC1tY3AucGFkZGxlLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgWU9VUl9BUElfS0VZIn19) [Install the Paddle MCP (live) in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=paddle-live&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnBhZGRsZS5jb20vbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfQVBJX0tFWSJ9fQ==) Before clicking Install, replace `YOUR_API_KEY` with your sandbox or live keys. ### Manual install 1. Open **Cursor Settings > MCP Tools** (or Command/Ctrl + Shift + J > **MCP Tools**). 2. Click Add Custom MCP to open the `mcp.json` file. 3. Add the `paddle-sandbox` and `paddle-live` servers to the `mcpServers` object. 4. Replace `SANDBOX_API_KEY` and `LIVE_API_KEY` with your sandbox and live keys. 5. Save the file and restart Cursor. ```json {% title="mcp.json" %} { "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" } } } } ``` {% /tab-item %} {% tab-item title="VS Code" %} ### One-click install [Install the Paddle MCP (sandbox) in VS Code](vscode:mcp/install?%7B%22name%22%3A%22paddle-sandbox%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A//sandbox-mcp.paddle.com/mcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20YOUR_API_KEY%22%7D%7D) [Install the Paddle MCP (live) in VS Code](vscode:mcp/install?%7B%22name%22%3A%22paddle-live%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A//mcp.paddle.com/mcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20YOUR_API_KEY%22%7D%7D) After installing, click the settings button and choose **Show configuration (JSON)** in the menu, then replace `YOUR_API_KEY` with your sandbox or live keys. ### Manual install 1. Press Command/Ctrl + Shift + P to open the command palette. 2. Search and select MCP: Open workspace folder MCP configuration... option. 3. Add the `paddle-sandbox` and `paddle-live` servers to the `mcpServers` object. 4. Replace `SANDBOX_API_KEY` and `LIVE_API_KEY` with your sandbox and live keys. 5. Save the file and restart VS Code. ```json {% title="mcp.json" %} { "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": [] } ``` {% /tab-item %} {% tab-item title="Mistral Vibe" %} Mistral Vibe configures MCP servers in `~/.vibe/config.toml`. 1. Export your Paddle API keys in your shell profile: ```sh export PADDLE_SANDBOX_API_KEY= # Your sandbox API key export PADDLE_LIVE_API_KEY= # Your live API key ``` 2. Add the `paddle-sandbox` and `paddle-live` servers to `~/.vibe/config.toml`: ```toml [[mcp_servers]] name = "paddle-sandbox" transport = "http" url = "https://sandbox-mcp.paddle.com/mcp" api_key_env = "PADDLE_SANDBOX_API_KEY" api_key_header = "Authorization" api_key_format = "Bearer {token}" [[mcp_servers]] name = "paddle-live" transport = "http" url = "https://mcp.paddle.com/mcp" api_key_env = "PADDLE_LIVE_API_KEY" api_key_header = "Authorization" api_key_format = "Bearer {token}" ``` 3. Restart Vibe so it picks up the new servers. [See the Mistral Vibe configuration docs for more options.](https://docs.mistral.ai/mistral-vibe/terminal/configuration) {% /tab-item %} {% tab-item title="Raycast" %} [Install the Paddle MCP (sandbox) in Raycast](raycast://mcp/install?%7B%22name%22%3A%22paddle-sandbox%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-remote%22%2C%22https%3A//sandbox-mcp.paddle.com/mcp%22%2C%22--header%22%2C%22Authorization%3A%20Bearer%20YOUR_API_KEY%22%5D%7D) [Install the Paddle MCP (live) in Raycast](raycast://mcp/install?%7B%22name%22%3A%22paddle-live%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-remote%22%2C%22https%3A//mcp.paddle.com/mcp%22%2C%22--header%22%2C%22Authorization%3A%20Bearer%20YOUR_API_KEY%22%5D%7D) After installing, replace `YOUR_API_KEY` with your Paddle API key. {% /tab-item %} {% tab-item title="Other" %} For any other MCP-compatible client, configure a server with these details: | Setting | Sandbox | Live | | ------- | ------------------------------------ | ---------------------------- | | Name | `paddle-sandbox` | `paddle-live` | | Type | `http` | `http` | | URL | `https://sandbox-mcp.paddle.com/mcp` | `https://mcp.paddle.com/mcp` | | Header | `Authorization: Bearer SANDBOX_API_KEY` | `Authorization: Bearer LIVE_API_KEY` | ```json { "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" } } } } ``` If your client doesn't support remote HTTP transport, proxy through `mcp-remote`: ```bash npx -y mcp-remote https://sandbox-mcp.paddle.com/mcp --header "Authorization: Bearer YOUR_API_KEY" ``` {% /tab-item %} {% /tabs %} ## 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`. {% callout type="danger" %} If you enable `--dangerously-skip-permissions` or similar setting in your client, your agent can run tools without your approval. This includes using the Paddle MCP server. {% /callout %} ## 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. ```markdown {% wrap=true %} 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. ```markdown {% wrap=true %} 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](https://developer.paddle.com/build/reports.md) and analyze it. Reports arrive as CSV files — the agent can retrieve them once ready. ```markdown {% wrap=true %} 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. ```markdown {% wrap=true %} 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. ```markdown {% wrap=true %} 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. ```markdown {% wrap=true %} 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.