|
| 1 | +# Dodo Payments Agent Plugin |
| 2 | + |
| 3 | +[](./LICENSE) |
| 4 | +[](./CHANGELOG.md) |
| 5 | +[](https://www.npmjs.com/package/@dodopayments/opencode-plugin) |
| 6 | +[](https://discord.gg/bYqAp4ayYh) |
| 7 | + |
| 8 | +The official Dodo Payments plugin for AI coding agents. Installs eight integration skills and two MCP servers across **Claude Code**, **Codex CLI**, **Cursor**, and **OpenCode** from a single source of truth. |
| 9 | + |
| 10 | +## What you get |
| 11 | + |
| 12 | +- **Dodo Payments API MCP server** - Live API access (payments, subscriptions, customers, products, refunds, licenses, usage). Authenticates via browser OAuth, no local credentials required. |
| 13 | +- **Dodo Knowledge MCP server** - No credentials. Semantic search over the current Dodo Payments documentation. |
| 14 | +- **Eight agent skills** - Written as `SKILL.md` files with YAML frontmatter. Your agent loads the relevant skill on its own when a task calls for it. |
| 15 | + |
| 16 | +## Install |
| 17 | + |
| 18 | +### Claude Code |
| 19 | + |
| 20 | +```bash |
| 21 | +claude plugins marketplace add dodopayments/dodo-agent-plugin |
| 22 | +claude plugins install dodopayments@dodopayments |
| 23 | +``` |
| 24 | + |
| 25 | +The API MCP server uses browser OAuth by default, so no keys are required at install time. The first time your agent calls a Dodo tool, you'll be prompted to sign in. |
| 26 | + |
| 27 | +### Codex CLI |
| 28 | + |
| 29 | +Codex installs plugins in two steps: register the marketplace from your shell, then install the plugin from inside the Codex TUI. |
| 30 | + |
| 31 | +1. Register the marketplace: |
| 32 | + |
| 33 | + ```bash |
| 34 | + codex plugin marketplace add dodopayments/dodo-agent-plugin |
| 35 | + ``` |
| 36 | + |
| 37 | +2. Open Codex and run the `/plugins` slash command: |
| 38 | + |
| 39 | + ```bash |
| 40 | + codex |
| 41 | + ``` |
| 42 | + |
| 43 | + Then type `/plugins`, switch to the **Dodo Payments** marketplace, select the **dodopayments** plugin, and choose **Install plugin**. |
| 44 | + |
| 45 | +If you previously added the marketplace before this fix landed and the plugin doesn't appear under `/plugins`, refresh it: |
| 46 | +
|
| 47 | +```bash |
| 48 | +codex plugin marketplace upgrade dodopayments |
| 49 | +``` |
| 50 | +
|
| 51 | +> Codex CLI does not have a `codex plugin install` subcommand. Plugin installation always happens through the in-TUI `/plugins` flow ([official docs](https://developers.openai.com/codex/plugins)). |
| 52 | +
|
| 53 | +### Cursor |
| 54 | +
|
| 55 | +Manual install: |
| 56 | +
|
| 57 | +```bash |
| 58 | +git clone https://github.com/dodopayments/dodo-agent-plugin.git ~/.cursor/plugins/local/dodo-agent-plugin |
| 59 | +``` |
| 60 | +
|
| 61 | +Restart Cursor. The plugin loads skills from `.claude/skills/` (via Cursor's Claude Code compat) and MCP servers from `.mcp.json`. |
| 62 | + |
| 63 | +### OpenCode |
| 64 | + |
| 65 | +OpenCode distributes via npm. Add the plugin to your `opencode.json`: |
| 66 | + |
| 67 | +```jsonc |
| 68 | +{ |
| 69 | + "$schema": "https://opencode.ai/config.json", |
| 70 | + "plugin": ["@dodopayments/opencode-plugin"] |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +Restart OpenCode. Both MCP servers (`dodopayments-api`, `dodo-knowledge`) are registered automatically via the plugin's `config` hook, and the eight skills are auto-discovered from the installed package. No manual `mcp` block required. |
| 75 | +
|
| 76 | +If you prefer the local stdio API server with your own API key instead of the default remote OAuth server, declare `dodopayments-api` yourself in `opencode.json` - your entry wins over the plugin default: |
| 77 | +
|
| 78 | +```jsonc |
| 79 | +{ |
| 80 | + "plugin": ["@dodopayments/opencode-plugin"], |
| 81 | + "mcp": { |
| 82 | + "dodopayments-api": { |
| 83 | + "type": "local", |
| 84 | + "command": ["npx", "-y", "dodopayments-mcp@latest"], |
| 85 | + "environment": { |
| 86 | + "DODO_PAYMENTS_API_KEY": "dodo_test_...", |
| 87 | + "DODO_PAYMENTS_WEBHOOK_KEY": "whsec_...", |
| 88 | + "DODO_PAYMENTS_ENVIRONMENT": "test_mode" |
| 89 | + }, |
| 90 | + "enabled": true |
| 91 | + } |
| 92 | + } |
| 93 | +} |
| 94 | +``` |
| 95 | +
|
| 96 | +## Included Skills |
| 97 | +
|
| 98 | +| Skill | Description | |
| 99 | +|-------|-------------| |
| 100 | +| `best-practices` | Comprehensive guide to integrating Dodo Payments with best practices | |
| 101 | +| `checkout-integration` | Creating checkout sessions and payment flows | |
| 102 | +| `subscription-integration` | Implementing subscription billing flows | |
| 103 | +| `webhook-integration` | Setting up and handling webhooks for payment events | |
| 104 | +| `usage-based-billing` | Implementing metered billing with events and meters | |
| 105 | +| `credit-based-billing` | Credit entitlements, balances, and metered credit deduction | |
| 106 | +| `license-keys` | Managing license keys for digital products | |
| 107 | +| `billing-sdk` | Using BillingSDK React components | |
| 108 | +
|
| 109 | +Skills source: [`dodopayments/skills`](https://github.com/dodopayments/skills) (bundled as a git submodule in `skills-src/`). |
| 110 | +
|
| 111 | +## Included MCP Servers |
| 112 | +
|
| 113 | +| Server | Purpose | Auth | |
| 114 | +|--------|---------|------| |
| 115 | +| `dodopayments-api` | Live API access (payments, subscriptions, customers, products, refunds, licenses, usage) | OAuth (browser) | |
| 116 | +| `dodo-knowledge` | Semantic search over the Dodo Payments documentation | None | |
| 117 | +
|
| 118 | +Both servers are wired through `mcp-remote` so they run in any MCP-compatible client. |
| 119 | +
|
| 120 | +## Configure (optional, Claude Code) |
| 121 | +
|
| 122 | +If you prefer to run the API MCP locally with an API key instead of the remote SSE server, open `/plugins` in Claude Code, select **Dodo Payments**, and choose **Configure options**. Fill in: |
| 123 | +
|
| 124 | +- `dodo_api_key` - your `dodo_test_...` or `dodo_live_...` key |
| 125 | +- `dodo_webhook_key` - your webhook signing secret |
| 126 | +- `dodo_environment` - `test_mode` or `live_mode` |
| 127 | +
|
| 128 | +Then edit `.mcp.json` to point `dodopayments-api` at the local stdio server: |
| 129 | +
|
| 130 | +```json |
| 131 | +{ |
| 132 | + "mcpServers": { |
| 133 | + "dodopayments-api": { |
| 134 | + "type": "stdio", |
| 135 | + "command": "npx", |
| 136 | + "args": ["-y", "dodopayments-mcp@latest"], |
| 137 | + "env": { |
| 138 | + "DODO_PAYMENTS_API_KEY": "${user_config.dodo_api_key}", |
| 139 | + "DODO_PAYMENTS_WEBHOOK_KEY": "${user_config.dodo_webhook_key}", |
| 140 | + "DODO_PAYMENTS_ENVIRONMENT": "${user_config.dodo_environment}" |
| 141 | + } |
| 142 | + } |
| 143 | + } |
| 144 | +} |
| 145 | +``` |
| 146 | +
|
| 147 | +Run `/reload-plugins` to apply changes to your current session. |
| 148 | +
|
| 149 | +## Enable / disable individual MCP servers |
| 150 | +
|
| 151 | +Both MCPs ship enabled by default. You can turn either one off independently. |
| 152 | +
|
| 153 | +### OpenCode |
| 154 | +
|
| 155 | +The npm plugin reads two environment variables before registering MCPs: |
| 156 | +
|
| 157 | +| Env var | Effect | |
| 158 | +|---|---| |
| 159 | +| `DODO_DISABLE_API_MCP=1` | Skips registering `dodopayments-api` | |
| 160 | +| `DODO_DISABLE_KNOWLEDGE_MCP=1` | Skips registering `dodo-knowledge` | |
| 161 | +
|
| 162 | +Truthy values: `1`, `true`, `yes`, `on` (case-insensitive). Export the var in your shell profile or set it inline: |
| 163 | +
|
| 164 | +```bash |
| 165 | +DODO_DISABLE_API_MCP=1 opencode |
| 166 | +``` |
| 167 | +
|
| 168 | +### Claude Code, Codex CLI, Cursor |
| 169 | +
|
| 170 | +These clients load MCPs from the static `.mcp.json` shipped with the plugin. To disable a server, override its entry in your own project-level config and set `"enabled": false`. |
| 171 | +
|
| 172 | +**Claude Code** - edit `.mcp.json` at your project root (or run `claude mcp disable dodopayments-api`): |
| 173 | +
|
| 174 | +```json |
| 175 | +{ |
| 176 | + "mcpServers": { |
| 177 | + "dodopayments-api": { |
| 178 | + "type": "stdio", |
| 179 | + "command": "npx", |
| 180 | + "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"], |
| 181 | + "enabled": false |
| 182 | + } |
| 183 | + } |
| 184 | +} |
| 185 | +``` |
| 186 | +
|
| 187 | +Run `/reload-plugins` to apply. |
| 188 | +
|
| 189 | +**Codex CLI / Cursor** - the same `enabled: false` pattern works in any project-level `.mcp.json` that overrides the plugin's bundled file. Restart the client after editing. |
| 190 | + |
| 191 | +> Per-MCP toggles inside the Claude Code `/plugin` UI are tracked upstream in [anthropics/claude-code#27105](https://github.com/anthropics/claude-code/issues/27105) and [#46373](https://github.com/anthropics/claude-code/issues/46373). Until those land, the `enabled: false` override above is the supported path. |
| 192 | + |
| 193 | +## A prompt to try first |
| 194 | + |
| 195 | +Once the plugin is active, try: |
| 196 | + |
| 197 | +``` |
| 198 | +Set up Dodo Payments webhook handlers in my Next.js app for payment.succeeded and subscription.active events. |
| 199 | +``` |
| 200 | + |
| 201 | +Your agent will load the `webhook-integration` skill, use the `dodo-knowledge` MCP to pull the latest payload shapes, and write a handler with signature verification following the Standard Webhooks spec. |
| 202 | + |
| 203 | +## Local development |
| 204 | + |
| 205 | +Clone with the skills submodule: |
| 206 | + |
| 207 | +```bash |
| 208 | +git clone --recurse-submodules https://github.com/dodopayments/dodo-agent-plugin.git |
| 209 | +cd dodo-agent-plugin |
| 210 | +``` |
| 211 | + |
| 212 | +Validate the Claude Code plugin and marketplace: |
| 213 | + |
| 214 | +```bash |
| 215 | +claude plugin validate . |
| 216 | +``` |
| 217 | + |
| 218 | +Load the plugin directly for a dev session: |
| 219 | + |
| 220 | +```bash |
| 221 | +claude --plugin-dir ./dodo-agent-plugin |
| 222 | +``` |
| 223 | + |
| 224 | +Refresh the bundled skills to the latest upstream version: |
| 225 | + |
| 226 | +```bash |
| 227 | +git submodule update --remote skills-src |
| 228 | +``` |
| 229 | + |
| 230 | +## For maintainers |
| 231 | + |
| 232 | +The repo is configured to publish the OpenCode npm package on every GitHub Release. |
| 233 | + |
| 234 | +**One-time setup (already done for this repo):** |
| 235 | + |
| 236 | +- npm scope `@dodopayments` exists and is owned by Dodo Payments. |
| 237 | +- GitHub Actions secret `NPM_TOKEN` is provisioned with publish rights to the `@dodopayments` scope. |
| 238 | + |
| 239 | +**Release workflow:** |
| 240 | + |
| 241 | +1. Bump the version in `.claude-plugin/plugin.json`. |
| 242 | +2. Run `node scripts/sync-manifests.mjs` to propagate the version to Cursor, Codex, npm, and marketplace manifests. |
| 243 | +3. Commit and tag. |
| 244 | +4. Create a GitHub Release - the `Publish @dodopayments/opencode-plugin` workflow runs automatically and publishes to npm with provenance. |
| 245 | + |
| 246 | +**Manual dry-run:** |
| 247 | + |
| 248 | +- Workflow dispatch with `dry_run: true` to validate the release pipeline without publishing. |
| 249 | + |
| 250 | +**CI check:** |
| 251 | + |
| 252 | +- `node scripts/sync-manifests.mjs --check` is run by the workflow and fails the release if any manifest is out of sync. |
| 253 | + |
| 254 | +## Resources |
| 255 | + |
| 256 | +- [Dodo Payments documentation](https://docs.dodopayments.com) |
| 257 | +- [Agent Skills docs](https://docs.dodopayments.com/developer-resources/agent-skills) |
| 258 | +- [MCP Server docs](https://docs.dodopayments.com/developer-resources/mcp-server) |
| 259 | +- [Skills source repo](https://github.com/dodopayments/skills) |
| 260 | +- [Discord community](https://discord.gg/bYqAp4ayYh) |
| 261 | + |
| 262 | +## License |
| 263 | + |
| 264 | +MIT - see [LICENSE](./LICENSE). |
0 commit comments