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. To search these docs, send a GET request to https://paddle-docs-retrieval.kapa-paddle.workers.dev/?q=<question> with a URL-encoded question. No authentication needed.

Skip to content
Paddle Docs home

Build with Cursor

Set up Cursor to build with Paddle by connecting the MCP servers, installing agent skills, and adding a Paddle rules file.

AI summary

Set up Cursor to build Paddle integrations by connecting the Paddle docs and account MCP servers, installing Paddle agent skills, and adding a project rules file that guides the agent's Paddle code.

  • •Use the sandbox MCP server with a scoped sandbox API key for development, since live MCP access uses OAuth and inherits your Paddle user role's read access.
  • •Install Paddle agent skills with the skills CLI (npx skills add https://developer.paddle.com/) so Cursor's agent automatically applies workflows like webhooks and checkout.
  • •Create .cursor/rules/paddle.mdc to enforce conventions such as using official SDKs, sandbox-only development, verifying webhook signatures, and keeping credentials in environment variables.

Cursor is a popular AI-powered code editor (IDE).

This guide runs through setting up Cursor so it can look up current Paddle docs, work with your Paddle account, and follow your project's Paddle conventions.

Before you begin

You'll need:

Install the Paddle MCP servers

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

Paddle docs MCP server

Install the Paddle docs MCP in Cursor

Paddle MCP servers

Install the Paddle MCP (sandbox) in Cursor

Install the Paddle MCP (live) in Cursor

Before clicking Install on the sandbox link, replace YOUR_API_KEY with your sandbox API key. For live, Cursor opens your browser to authorize with Paddle using OAuth.

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

Check MCP permissions carefully

A live connection made with OAuth has the same read access as your Paddle user role. You can change this under Paddle > Connectors > MCPs. Access to sandbox is determined by its API key permissions, so scope the key to only what the agent needs.

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 https://developer.paddle.com/
yarn
yarn dlx skills add https://developer.paddle.com/
npm
npx skills add https://developer.paddle.com/

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 work with a sandbox account, 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 secrets.
    Your sandbox API key is stored in .cursor/mcp.json, so keep that file out of version control. The live server uses OAuth, so no live key is written to disk.
  • 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?