> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Build with Cursor

Use Cursor to integrate Paddle — install the MCP servers, write a Paddle rules file, and prompt the agent to scaffold checkout, subscriptions, and webhooks.

---

[Cursor](https://cursor.com) integrates with Paddle through two MCP servers and a project rules file. The docs MCP server keeps Cursor's agent grounded in current Paddle documentation; the Paddle MCP server lets it read and act on your account. A `.cursor/rules/paddle.mdc` file codifies the conventions you want every Cursor-generated change to follow.

This guide focuses on the Paddle-specific workflow. For full MCP setup details — including one-click install URLs and detailed setup for every supported client — see the [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp.md) and [docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp.md) reference pages.

## Before you begin

- A Paddle [sandbox account](https://developer.paddle.com/sdks/sandbox.md) and [API key](https://developer.paddle.com/api-reference/about/api-keys#create-api-key.md).
- Cursor installed.
- A Paddle SDK installed in your project (or planned) — the rules file references it.

## 1. Install the Paddle MCP servers {% step=true %}

Add both MCP servers to Cursor — the Docs MCP for current Paddle knowledge, the Paddle MCP for taking actions in your account.

{% card-group cols=2 %}
{% card title="Paddle MCP server" icon="carbon:api-1" url="/sdks/ai/paddle-mcp#install-the-mcp-server" %}
Read and act on your Paddle account. One-click install for Cursor available.
{% /card %}
{% card title="Docs MCP server" icon="carbon:book" url="/sdks/ai/docs-mcp#install-the-docs-mcp-server" %}
Search the latest Paddle docs, OpenAPI spec, and SDK references.
{% /card %}
{% /card-group %}

The fastest path is the **one-click install** links on both reference pages. They open Cursor and prefill the configuration — you just supply your sandbox API key for the Paddle MCP and save.

For manual setup, add both servers to `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global setup):

```json
{
  "mcpServers": {
    "paddle": {
      "command": "npx",
      "args": [
        "-y",
        "@paddle/paddle-mcp",
        "--api-key=YOUR_SANDBOX_API_KEY",
        "--environment=sandbox",
        "--tools=non-destructive"
      ]
    },
    "paddle-docs": {
      "type": "http",
      "url": "https://paddlehq.mcp.kapa.ai"
    }
  }
}
```

{% callout type="warning" %}
Use a sandbox API key while you're learning. The `--tools=non-destructive` scope lets the agent create and read, but not update or archive. Widen to `all` only when you trust the workflow.
{% /callout %}

## 2. Add a Paddle rules file {% step=true %}

Cursor reads project rules from `.cursor/rules/*.mdc` files. A focused rules file tells the agent what conventions to follow when it writes Paddle code — which SDK to use, how to handle the sandbox boundary, and where to source current syntax.

Create `.cursor/rules/paddle.mdc`:

```markdown
---
description: Conventions for Paddle integration code
globs: ["**/*.ts", "**/*.tsx", "**/*.py", "**/*.go", "**/*.php"]
alwaysApply: true
---

# Paddle integration rules

When writing or modifying code that integrates with Paddle:

- Always check current Paddle documentation via the paddle-docs MCP server
  before suggesting code. Do not rely on training data — the API and SDK
  evolve frequently.
- Prefer the official Paddle SDK for the language in use (paddle-node-sdk,
  paddle-python-sdk, paddle-go-sdk, paddle-php-sdk) over raw HTTP calls.
- All development uses the sandbox environment. Sandbox API keys contain
  _sdbx; sandbox client-side tokens are prefixed with test_.
- Always verify webhook signatures before acting on the payload. In Node,
  use paddle.webhooks.unmarshal(). In Python, Verifier().verify(). In Go,
  paddle.NewWebhookVerifier(). In PHP, (new Verifier())->verify().
- For destructive account changes (updating prices, archiving products),
  ask for explicit confirmation before calling the paddle MCP server.
- Use environment variables for API keys and webhook secrets. Never inline
  credentials into code.
```

Adjust the `globs` to match the languages in your project. Cursor will load this rule file whenever it edits matching files.

## 3. Prompt your first integration {% step=true %}

With both MCP servers connected and the rules file in place, ask Cursor's agent to add a Paddle integration to your project.

```markdown {% wrap=true %}
Add a Paddle Checkout integration to this Next.js app. Use the paddle-docs MCP server to look up the current Paddle.js syntax. Then use the paddle MCP server to create three products in my sandbox account — Starter ($10/mo), Pro ($30/mo), Enterprise ($300/mo) — and generate a /pricing page that opens checkout for each tier. Wire up a /api/webhooks route that verifies the signature and logs transaction.completed events.
```

Cursor will use the Docs MCP for current syntax, the Paddle MCP to create the products in sandbox, and write code that follows your rules file conventions.

## Example workflows

A few prompts that demonstrate the integration's range:

```markdown {% wrap=true %}
Investigate why Paddle webhook signature verification is failing in this codebase. Use the paddle-docs MCP server to confirm the current verification flow, then check my code and tell me what's wrong.
```

```markdown {% wrap=true %}
Add usage-based billing to my AI app. Customers pay $20/mo base plus $0.001 per generation. Use the paddle-docs MCP server to find the right pricing model, then create the product and prices in my sandbox account, and generate the metering code that adds custom items to the upcoming transaction.
```

```markdown {% wrap=true %}
Audit my Paddle integration. Use the paddle-docs MCP server to check best practices, then review my webhook handler, environment switching, and error handling. Tell me what to change.
```

## Best practices

- **Mention Paddle and the relevant MCP server explicitly.** "Use the paddle-docs MCP server to look up X" beats hoping the agent calls it on its own.
- **Be specific in prompts.** Concrete pricing, event names, and entity IDs work better than vague descriptions.
- **Review changes before applying.** Cursor's agent makes mistakes — especially around webhook signature verification and environment switching.
- **Sandbox-only credentials in `.cursor/mcp.json`.** Never commit live API keys. Add `.cursor/mcp.json` to `.gitignore` if it contains secrets.
- **Iterate the rules file.** When the agent makes a recurring mistake, encode the fix as a rule.

## Troubleshooting

{% accordion %}
{% accordion-item title="Agent ignores the rules file" %}
Check that `.cursor/rules/paddle.mdc` is in the project root, the `globs` match the file types you're editing, and `alwaysApply: true` is set. Restart Cursor after creating the file.
{% /accordion-item %}
{% accordion-item title="MCP server not connecting" %}
Open **Cursor Settings > MCP Tools** to see connection status and recent errors. Check that the API key is valid and the JSON config is well-formed.
{% /accordion-item %}
{% accordion-item title="Agent generates outdated Paddle syntax" %}
Prompt explicitly: *"Use the paddle-docs MCP server to check the current syntax before generating this."* If it still happens, confirm the Docs MCP is authenticated — you may have been logged out of Kapa.ai.
{% /accordion-item %}
{% /accordion %}