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

# Build with Codex

Set up Codex for the best possible Paddle workflow by installing the Paddle plugin, connecting the Paddle MCP server, and adding an AGENTS.md file.

---

[Codex](https://developers.openai.com/codex) is OpenAI's AI coding agent. It runs as a CLI, an IDE extension, and on the web.

This guide runs through setting up Codex 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.
- Codex installed.
- A project, with a Paddle SDK installed.

## Install the Paddle plugin {% step=true %}

The Paddle plugin bundles [Paddle agent skills](https://developer.paddle.com/sdks/ai/agent-skills.md) with the [docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp.md) and [Paddle MCP servers](https://developer.paddle.com/sdks/ai/paddle-mcp/.md).

From your terminal, run:

```bash
codex plugin marketplace add PaddleHQ/paddle-agent-skills
```

Then open Codex and install the `paddle` plugin from the plugin directory.

To refresh later, run `codex plugin marketplace upgrade paddle-agent-skills`.

## Set your Paddle API keys {% step=true %}

The plugin wires up two Paddle MCP servers so the agent can work in both sandbox and live environments. This is useful for porting data from one to the other.

| MCP server       | URL                                  | API key env var          |
| ---------------- | ------------------------------------ | ------------------------ |
| `paddle-sandbox` | `https://sandbox-mcp.paddle.com/mcp` | `PADDLE_SANDBOX_API_KEY` |
| `paddle-live`    | `https://mcp.paddle.com/mcp`         | `PADDLE_LIVE_API_KEY`    |

They read API keys from environment variables. Export them in your shell profile (`~/.zshrc`, `~/.bashrc`, or equivalent):

```sh
export PADDLE_SANDBOX_API_KEY= # Your sandbox API key
export PADDLE_LIVE_API_KEY= # Your live API key
```

[Create API keys](https://developer.paddle.com/api-reference/about/authentication.md) at **Paddle > Developer tools > Authentication**.

Restart Codex and your terminal after setting the variables so the MCP servers pick them up. The skills default to sandbox unless you've explicitly opted into live, so `PADDLE_SANDBOX_API_KEY` is the one to start with during development.

{% callout type="warning" %}
Start with a sandbox API key while you're evaluating. Scope your live API key narrowly, since the Paddle MCP server doesn't gate destructive operations on its own. See [Permissions and destructive actions](https://developer.paddle.com/sdks/ai/paddle-mcp#permissions-and-destructive-actions.md) for details.
{% /callout %}

## Add Paddle conventions to your AGENTS.md {% step=true %}

Codex reads project conventions from `AGENTS.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 an `AGENTS.md` file at the project root, or add this to your existing `AGENTS.md` file.

```markdown {% title="AGENTS.md" wrap=true %}
## 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-sandbox` or `paddle-live` MCP server.
- Use `paddle-sandbox` by default. Only call `paddle-live` when the prompt explicitly mentions live, production, or real customer data.
- 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. Codex will read this every time you start a session.

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

With the plugin installed, the Paddle MCP server connected, and your `AGENTS.md` file in place, ask Codex to scaffold a Paddle integration.

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

Codex 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 `AGENTS.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.
- **Be specific in prompts.**  
  Concrete pricing, event names, and entity IDs work better than vague descriptions.
- **Review changes before applying.**  
  Codex shows pending tool calls before executing. Review every tool call, especially anything destructive.
- **Never commit API keys.**  
  Keep API keys in environment variables.
- **Create your own skills.**  
  When you find yourself repeating the same instructions over and over, package them as a skill. Run the `$plugin-creator` skill in Codex to walk through it.