For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

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.

AI summary

Set up Cursor for Paddle development by installing the Paddle and docs MCP servers via one-click deep links, adding agent skills, and creating a .cursor/rules/paddle.mdc rules file with SDK and webhook conventions.

  • • One-click deep links are available to install both the Paddle MCP server and docs MCP server in Cursor without manual JSON config editing.
  • • The .cursor/rules/paddle.mdc file uses globs to scope rules to matching file types, so Cursor applies Paddle conventions only when editing relevant code.
  • • Always mention the relevant MCP server explicitly in prompts — the agent won't call it reliably without the explicit instruction.

Cursor 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:

Install the Paddle MCP servers

Paddle includes two MCP servers. The Paddle MCP server can create and update entities in your Paddle account, and the docs MCP server can search the latest Paddle docs, API spec, and SDK references.

Install the Paddle MCP server in Cursor

Install the Paddle docs MCP in Cursor

For manual setup, see the Paddle MCP server and docs MCP server reference pages.

Install Paddle agent skills

Agent skills give Cursor's agent drop-in instructions for specific Paddle workflows.

Install all Paddle skills with the skills CLI:

pnpm
pnpm dlx skills add @PaddleHQ/paddle-agent-skills
yarn
npx skills add @PaddleHQ/paddle-agent-skills
npm
npx skills add @PaddleHQ/paddle-agent-skills

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 for the full list, manual install commands, and the discovery index URL.

Add a Paddle rules file

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:

paddle.mdc
---
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

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
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.

Was this page helpful?