Paddle MCP Server

The Paddle MCP Server connects an AI assistant to a Paddle account. It is the operational account connector in Paddle's official AI tooling, rather than the separate Paddle Docs MCP Server. That distinction matters: documentation can explain an integration, but account tools may interact with real business records. A software team might use the connector to investigate a billing issue or prepare a change to its product catalog. This entry is based on a review of official documentation, not an authenticated hands-on test against a Paddle account.

An account connection, not a documentation search

Paddle describes support for pricing work, subscription operations, payment investigations, reports, and integration tasks. The useful boundary is the team's own Paddle environment, not arbitrary financial systems. Start with a small question about an existing catalog and a clearly defined expected result. When the task is simply understanding a webhook signature or an SDK example, the documentation connector is the more appropriate starting point. There is no reason to grant customer-data access just to look up development guidance.

Hosted endpoints and separate environments

The MCP service runs remotely and is reached over HTTPS. Sandbox uses https://sandbox-mcp.paddle.com/mcp, while the production endpoint is https://mcp.paddle.com/mcp. Paddle's sandbox documentation explains that test and live accounts have separate datasets and credentials. A successful test does not publish the same products into production. Give the connections distinguishable names and specify the intended environment in each request. Before applying a plan, verify that the selected account and the referenced record identifiers belong to the correct environment.

Authentication and limited permissions

Sandbox access requires a sandbox API key supplied as a bearer token; it does not support OAuth. For a live account, the official MCP instructions support OAuth or a live API key. An OAuth connection begins with the read access allowed by the user's Paddle role, with permissions managed through the dashboard's Connectors and MCP area. API keys instead follow their assigned scopes. Keep those scopes specific: a catalog-reading integration should not automatically receive transaction-writing privileges. Avoid pasting credentials into prompts or committing client configuration containing secrets.

A workflow that can be reviewed

The documented codemode interface exposes search, execute, and report_missing_tool. The agent can discover an API operation and then combine calls inside a JavaScript function. This supports multi-step investigations, but a natural-language instruction should still describe a bounded objective. Include the relevant record identifiers, time range, and environment. For a proposed subscription change, request an impact preview and wait for human approval before execution. Preserve the distinction between an analysis result and an instruction to change an account.

Costs and data boundaries

The reviewed pages do not list a separate MCP connection price. Paddle's payment platform remains a commercial service, and the official pricing page should be checked for current terms. Model-provider or client charges may also apply. Results returned from the account service become available to the AI client; what happens next depends on that client's configuration and provider. Do not infer local-only processing, a particular retention period, or a no-training guarantee from the fact that the connector uses MCP. Minimize sensitive customer information in investigative prompts.

Who should use the Paddle MCP Server?

It is relevant to developers and operations teams already working with Paddle who want assistance with recurring account tasks. Evaluate it in sandbox with narrow read permissions before considering live write access. According to Paddle, the server does not add a mandatory approval gate for destructive operations: annotations and warnings are not an authorization boundary. Enable confirmation in the client and inspect important changes both before and after they run. A fluent answer is not proof that the correct records were selected or that a business rule was respected. Teams needing only reference information should use the Docs MCP Server instead.

A Paddle account for the intended sandbox or live environment and an HTTP-capable MCP client. Sandbox requires a scoped sandbox API key; live supports OAuth or a live API key.

This walkthrough uses an installed, signed-in Claude Code client. Start with Docs MCP; sandbox and live account access are separate, optional additions. A Cursor configuration follows the numbered steps. The instructions were checked against official documentation, not authenticated against a personal Paddle account during research.

Step 1: Check Claude Code

Open a terminal in the project folder and check that the client is available:

claude --version

Expected result: a version number. If the command is not found, install the client using its official instructions first. The bash boxes below contain terminal commands. Text boxes contain messages for the AI client, not commands to execute in the shell.

Step 2: Add Paddle Docs MCP

Run this in the terminal. It registers the documentation connection and needs no Paddle API key:

claude mcp add --transport http paddle-docs https://paddlehq.mcp.kapa.ai

Expected result: confirmation that paddle-docs was added. Restart an existing client session if necessary. This service retrieves public Paddle documentation, OpenAPI specifications, and SDK references; it cannot change the team's Paddle account records.

Step 3: Authenticate the Docs connection

Start an interactive Claude Code session in the project:

claude

Enter the following inside that session, not in the regular shell:

/mcp

Select paddle-docs and follow the available authentication flow. Kapa.ai hosts this service and requires Google or GitHub sign-in for rate limiting and abuse prevention. No Paddle account is needed. Expected result: the client shows an authenticated, available connection. If access stops working later, check whether sign-in needs to be renewed.

Step 4: Test documentation lookup

Send this read-only request in Claude Code:

Use paddle-docs to explain how to verify a Paddle webhook signature. Cite the matching official reference. Do not change files or account data.

Expected result: an answer grounded in an official reference. Verify the source and the SDK version used by the project. Keep real customer records, API credentials, and private billing information out of lookup examples. If reference information is all you need, stop here.

Step 5: Add sandbox account access – optional

Create a separate Paddle sandbox and issue a sandbox API key with only the read permissions needed for the test, such as products and prices. Sandbox and live have separate credentials and data. This MCP server does not support OAuth in sandbox.

Replace SANDBOX_API_KEY below with your own sandbox key. Never share real keys in chats, screenshots, or repositories. The supplied key can appear in local client configuration and shell history: protect those files and prefer narrowly scoped, revocable credentials.

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

Expected result: a second connection named paddle-sandbox. Open /mcp in the Claude session again and check its availability. A live key cannot authenticate against this sandbox endpoint.

Step 6: Try a small sandbox read request

Enable tool approval in the client. Then send this request, explicitly naming the environment:

Use only paddle-sandbox. Show no more than five products from my sandbox catalog. Do not perform any write operations.

Compare the result with the sandbox dashboard. Consider additional permissions only after confirming the environment and records. A successful read proves that particular lookup, not the safety of every tool the service offers.

Step 7: Add live access – optional

Only if production account access is required, register a separate live connection in the terminal:

claude mcp add --transport http paddle-live https://mcp.paddle.com/mcp

Open /mcp in Claude Code and complete Paddle OAuth for paddle-live. OAuth starts with read access allowed by the user's Paddle role. Review permissions in the Paddle dashboard under Connectors and MCP. Live also supports a live API key for environments without browser sign-in; a sandbox key is not suitable for it.

Step 8: Review the configured connections

List the registered MCP connections from the terminal:

claude mcp list

Expect only the names you actually added: paddle-docs and, optionally, paddle-sandbox and paddle-live. Also check connection and authentication status through /mcp in the client. When something fails, verify the server name, endpoint, environment, and credentials first. Documentation lookup needs no Paddle permissions; account requests require the appropriate entity scopes.

Step 9: Plan and approve changes separately

Before granting write access, ask for an explanation of a proposed account change and its impact. A suitable sandbox request is:

Use only paddle-sandbox. Plan the requested change and preview the affected records. Wait for my explicit approval before executing any change.

The account service can combine API calls through execute. Paddle states that there is no extra server-side confirmation gate for destructive operations. Warnings do not replace least privilege or client approval. Review important changes before and after execution, and do not carry sandbox plans or test record identifiers into live without checking them.

Alternative: configure the connections in Cursor

Open Cursor settings for MCP Tools, then Add Custom MCP. Merge these entries into the existing mcpServers configuration without replacing other servers. Remove paddle-sandbox or paddle-live if those connections are not needed. SANDBOX_API_KEY is a placeholder, not a working credential.

{
  "mcpServers": {
    "paddle-docs": {
      "type": "http",
      "url": "https://paddlehq.mcp.kapa.ai"
    },
    "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"
    }
  }
}

Save and restart Cursor if needed. Sign in with Google or GitHub for paddle-docs and through Paddle OAuth for paddle-live. Begin with documentation lookup or a sandbox read request. Keep configuration containing real API keys out of version control.

Costs, privacy, and original references

The reviewed pages list no separate MCP price. Paddle platform fees and AI-client or model costs remain distinct considerations. Documentation questions go to a hosted service, and account tools can return sensitive business records. Neither local-only processing nor specific retention periods should be assumed. Check current client-specific setup and authentication notes at https://developer.paddle.com/sdks/ai/paddle-mcp/ and https://developer.paddle.com/sdks/ai/docs-mcp/.

Live: Paddle OAuth or a live API key as a bearer token. Sandbox: a sandbox API key as a bearer token only; no OAuth.

OAuth starts with read access permitted by the user role; additional permissions are managed in the dashboard. API keys follow their entity and read/write scopes. Depending on authorization, products, prices, subscriptions, and other account data can be changed.

Account access runs through Paddle's hosted service. Results may contain customer and billing data and are returned to the MCP client. Further transmission to a model provider depends on the client; local-only processing or specific retention periods are not established.

According to Paddle, the server does not enforce an additional confirmation gate for destructive actions. Warnings are not access controls. Environment mix-ups, excessive write permissions, exposed keys, and sensitive account data in model context are important risks. Use client approval and least privilege.