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 Claude Code

Set up Claude Code for the best possible Paddle workflow by installing the Paddle plugin, connecting the Paddle MCP server, and adding a CLAUDE.md file.

AI summary

Set up Claude Code for Paddle development by installing the Paddle and docs MCP servers, adding agent skills, and creating a CLAUDE.md file with SDK conventions and webhook verification guidance.

  • • Run two claude mcp add commands to connect the Paddle MCP server (for creating entities) and the docs MCP server (for searching up-to-date Paddle docs) — both are needed for the full workflow.
  • • Install Paddle agent skills via pnpm dlx skills add @PaddleHQ/paddle-agent-skills to drop context-aware Paddle workflow instructions into .agents/skills/.
  • • Always mention the relevant MCP server explicitly in prompts (e.g. 'use the paddle-docs MCP server') — the agent won't call it reliably without the explicit instruction.

Claude Code is an AI-powered coding assistant that helps you build features, fix bugs, and automate development tasks. It works as a CLI, IDE extension, or as part of the Claude Desktop app.

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

Before you begin

You'll need:

Install the Paddle plugin

The Paddle plugin bundles Paddle agent skills with the docs MCP server. Agent skills add drop-in instructions for Paddle-specific workflows, while the docs MCP gives Claude real-time access to the latest Paddle docs for troubleshooting and planning.

Inside Claude Code, run:

Shell
/plugin marketplace add PaddleHQ/paddle-agent-skills
/plugin install paddle@paddle-agent-skills

Claude Code automatically picks the relevant skill as you work. For example, paddle-webhooks when you ask it to set up webhook handling, paddle-checkout-web when adding checkout to a page, and so on.

To update later, run /plugin marketplace update paddle-agent-skills.

Install the Paddle MCP server

The Paddle MCP server lets Claude Code create and update entities in your Paddle account on your behalf.

Run this command from your terminal. Replace YOUR_API_KEY with a sandbox API key.

Shell
claude mcp add paddle -- npx -y @paddle/paddle-mcp \
  --api-key=YOUR_API_KEY \
  --environment=sandbox \
  --tools=non-destructive

For manual setup, see the Paddle MCP server reference page.

Add Paddle conventions to your CLAUDE.md

Claude Code reads project conventions from CLAUDE.md at the project root. A focused Paddle section tells it which SDK to use, how to handle environments, and how to verify webhooks.

Create a CLAUDE.md file at the project root, or add it to your existing CLAUDE.md file.

CLAUDE.md
## Paddle integration


When writing or modifying code that integrates with Paddle:


- Always check current Paddle documentation via the `paddle-docs` MCP server before suggesting code. The Paddle API and SDKs evolve frequently — do not rely on training data alone.
- Use the official Paddle SDK for the language in use:
  - Node.js → `@paddle/paddle-node-sdk`
  - Python → `paddle-python-sdk` (imports as `paddle_billing`)
  - Go → `github.com/PaddleHQ/paddle-go-sdk/v5`
  - PHP → `paddlehq/paddle-php-sdk`
- 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:
  - Node: `paddle.webhooks.unmarshal()`
  - Python: `Verifier().verify(request, secret)`
  - Go: `paddle.NewWebhookVerifier()` with `Middleware`
  - PHP: `(new Verifier())->verify($request, $secret)`
- For destructive account changes (updating prices, archiving products, cancelling subscriptions), ask for explicit confirmation before calling the `paddle` MCP server.
- API keys and webhook secrets live in environment variables — never inline credentials into code.

Adjust the SDK list to match the language(s) your project uses. Claude Code will read this every time you start a session.

Prompt your first integration

With the plugin installed, the Paddle MCP server connected, and your CLAUDE.md file in place, ask Claude Code to scaffold a Paddle integration.

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.

Claude Code plans first, then uses the docs MCP for current syntax, the Paddle MCP to create the products in sandbox, and writes code that matches your CLAUDE.md 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.
  • Use Plan mode first. For complex integrations, enter plan mode to draft a plan before writing code. Approve, then run.
  • Be specific in prompts. Concrete pricing, event names, and entity IDs work better than vague descriptions.
  • Review changes before applying.
    Claude Code shows pending tool calls before executing. Review every tool call, especially anything destructive.
  • Never commit API keys. Never commit API keys. Add .cursor/mcp.json to .gitignore if it contains secrets.
  • Create your own skills.
    When you find yourself repeating the same instructions over and over, create a skill to help steer Claude Code. Run /skill-creator to walk through the process with Claude.

Was this page helpful?