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

# Build with Cursor

Set up Cursor for the best possible Paddle workflow by connecting the MCP servers, installing agent skills, and adding a Paddle rules file.

---

[Cursor](https://cursor.com) is a popular AI-powered code editor (IDE), built as a fork of VS Code.

This guide runs through setting up Cursor for the best possible experience when building with Paddle.

## Before you begin

You'll need:

- A Paddle [sandbox account](https://developer.paddle.com/sdks/sandbox.md)
- A [sandbox API key](https://developer.paddle.com/api-reference/about/authentication.md) with any permissions you plan to use.
- Cursor installed.
- A project, with a Paddle SDK installed.

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

Paddle includes two MCP servers. The [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp.md) can create and update entities in your Paddle account, and [the docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp.md) can search the latest Paddle docs, API spec, and SDK references.

[Install the **Paddle MCP server** in Cursor](https://cursor.com/en-US/install-mcp?name=paddle&config=eyJlbnYiOnsiUEFERExFX0FQSV9LRVkiOiJ5b3VyX2FwaV9rZXkiLCJQQURETEVfRU5WSVJPTk1FTlQiOiJzYW5kYm94IiwiUEFERExFX01DUF9UT09MUyI6Im5vbi1kZXN0cnVjdGl2ZSJ9LCJjb21tYW5kIjoibnB4IC15IEBwYWRkbGUvcGFkZGxlLW1jcCJ9)

[Install the **Paddle docs MCP** in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=paddle-docs&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vcGFkZGxlaHEubWNwLmthcGEuYWkifQ==)

For manual setup, 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.

{% callout type="warning" %}
Use a sandbox API key while you're getting started. 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 %}

## Install Paddle agent skills {% step=true %}

[Agent skills](https://developer.paddle.com/sdks/ai/agent-skills.md) give Cursor's agent drop-in instructions for specific Paddle workflows.

Install all Paddle skills with the skills CLI:

{% code-group sync="js-package-manager" %}

```bash {% title="pnpm" %}
pnpm dlx skills add @PaddleHQ/paddle-agent-skills
```

```bash {% title="yarn" %}
npx skills add @PaddleHQ/paddle-agent-skills
```

```bash {% title="npm" %}
npx skills add @PaddleHQ/paddle-agent-skills
```

{% /code-group %}

This drops them into `.agents/skills/` in your project. From there, Cursor's agent picks the relevant skill automatically as you work. For example, it uses `paddle-webhooks` when you ask it to set up webhook handling, `paddle-checkout-web` when adding checkout to a page, and so on.

See [agent skills](https://developer.paddle.com/sdks/ai/agent-skills.md) for the full list, manual install commands, and the discovery index URL.

## 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. For example, which SDK to use, how to handle the sandbox environment, and where to source current syntax.

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

```markdown {% title="paddle.mdc" wrap=true %}
---
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, use `Verifier().verify()`. In Go, use `paddle.NewWebhookVerifier()`. In PHP, use `(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 loads this rule file whenever it edits matching files.

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

With MCP servers connected, the Paddle skills installed, 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 uses the Docs MCP for current syntax, the Paddle MCP to create the products in sandbox, and writes code that follows your rules file conventions.

## 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.**  
  AI can make mistakes. Billing is an important part of your business, so double-check before applying changes.
- **Never commit API keys.**
  Never commit API keys. Add `.cursor/mcp.json` to `.gitignore` if it contains secrets.
- **Iterate on the rules file.**  
  When the agent makes a recurring mistake, encode the fix as a rule. Evolve the file to match your project conventions.