{
  "markdown": "# Dodo Payments Agent Plugin\n\n[![License](https://img.shields.io/github/license/dodopayments/dodo-agent-plugin.svg?style=flat-square)](./LICENSE)\n[![Version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdodopayments%2Fdodo-agent-plugin%2Fmain%2Fplugin.json&query=%24.version&label=version&color=blue&style=flat-square)](./CHANGELOG.md)\n[![npm](https://img.shields.io/npm/v/@dodopayments/opencode-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@dodopayments/opencode-plugin)\n[![Discord](https://img.shields.io/discord/1305511580854779984?label=discord&style=flat-square)](https://discord.gg/bYqAp4ayYh)\n\nThe official Dodo Payments plugin for AI coding agents. Installs seventeen integration skills and two MCP servers across **Claude Code**, **Codex CLI**, **Cursor**, **VS Code / GitHub Copilot**, and **OpenCode** from a single source of truth.\n\nThis plugin conforms to the [Agent Plugins 1.0.0](https://agent-plugins.org/specification) specification: a root [`plugin.json`](./plugin.json), skills as immediate children of [`skills/`](./skills), and MCP servers in [`mcp.json`](./mcp.json). Clients with native Agent Plugins support load it directly; the provider-specific manifests in this repo are generated compatibility shims for clients that do not.\n\n## What you get\n\n- **Dodo Payments API MCP server** - Live API access (payments, subscriptions, customers, products, refunds, licenses, usage). Authenticates via browser OAuth, no local credentials required.\n- **Dodo Knowledge MCP server** - No credentials. Semantic search over the current Dodo Payments documentation.\n- **Seventeen 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.\n\n## Install\n\n### Claude Code\n\n```bash\nclaude plugins marketplace add dodopayments/dodo-agent-plugin\nclaude plugins install dodopayments@dodopayments\n```\n\nThe 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.\n\n### Codex CLI\n\nRegister the marketplace, then install the plugin:\n\n```bash\ncodex plugin marketplace add dodopayments/dodo-agent-plugin\ncodex plugin add dodopayments@dodopayments\n```\n\nVerify:\n\n```bash\ncodex plugin list     # dodopayments  installed, enabled\ncodex mcp list        # dodo-knowledge, dodopayments-api\ncodex mcp login dodopayments-api    # browser OAuth, only needed for the API server\n```\n\nYou can also install from inside the TUI: run `codex`, type `/plugins`, select the **Dodo Payments** marketplace and the **dodopayments** plugin, then choose **Install plugin**.\n\nIf you added the marketplace previously and the plugin doesn't appear, refresh it:\n\n```bash\ncodex plugin marketplace upgrade dodopayments\n```\n\n### Cursor\n\nManual install:\n\n```bash\ngit clone https://github.com/dodopayments/dodo-agent-plugin.git ~/.cursor/plugins/local/dodo-agent-plugin\n```\n\nRestart Cursor. The plugin loads skills from `skills/` and MCP servers from `.mcp.json`, as declared in `.cursor-plugin/plugin.json`.\n\n> Cursor 3.14.27 also recognises Agent Plugins 1.0.0 directly: its agent host carries both spec schema URLs and the spec's own `name` regex, and accepts either `.cursor-plugin/marketplace.json` or `.claude-plugin/marketplace.json` as a marketplace source. The generated `.cursor-plugin/plugin.json` is kept as belt-and-braces for older builds.\n\n> Prior to v0.5.0 this clone produced a plugin with **no working skills**: `skills/` contained symlinks into a git submodule that a plain `git clone` does not fetch. Skills are now vendored as real files, so the command above works as documented. If you installed an earlier version, re-clone.\n\n### Kiro\n\nKiro reads the Agent Plugins manifest natively and loads this as a Power:\n\n```bash\ngit clone https://github.com/dodopayments/dodo-agent-plugin.git\n```\n\nPoint Kiro at the cloned folder. Skills load from `skills/`, MCP servers from `mcp.json`, and Kiro-specific presentation comes from the `dev.kiro` extension namespace in `plugin.json`.\n\n### Gemini CLI (MCP only)\n\nGemini CLI has no agent-skill primitive, so **only the two MCP servers are available** - the seventeen skills are not. `dodo-knowledge` still covers a good share of what the skills provide, and it stays current automatically.\n\n```bash\ngit clone https://github.com/dodopayments/dodo-agent-plugin.git \\\n  ~/.gemini/extensions/dodopayments\n```\n\nRestart Gemini CLI. `gemini-extension.json` at the repo root is the manifest.\n\n### VS Code / GitHub Copilot\n\n```bash\ngit clone https://github.com/dodopayments/dodo-agent-plugin.git\n```\n\nThen open the Chat view, go to **Plugins**, and add the cloned folder. Skills load from `skills/`, and both MCP servers load from `.mcp.json`.\n\n> VS Code 1.125.1 does not key off the Agent Plugins `$schema` - the string appears nowhere in its bundle. Its loader picks a manifest by probing, in order, `.plugin/plugin.json`, then `.claude-plugin/plugin.json`, then a root `plugin.json`, and defaults MCP to `.mcp.json` rather than `mcp.json`. Because this repo ships a generated `.claude-plugin/plugin.json`, VS Code loads it through that branch. Everything works - seventeen skills and two MCP servers - but via the compatibility manifests rather than the spec ones, so VS Code gets the `mcp-remote` bridge rather than the native transports in `mcp.json`.\n\n### OpenCode\n\nOpenCode distributes via npm. Add the plugin to your `opencode.json`:\n\n```jsonc\n{\n    \"$schema\": \"https://opencode.ai/config.json\",\n    \"plugin\": [\"@dodopayments/opencode-plugin\"]\n}\n```\n\nRestart OpenCode. Both MCP servers (`dodopayments-api`, `dodo-knowledge`) are registered automatically via the plugin's `config` hook. No manual `mcp` block required.\n\n**Skills need the package installed locally plus one extra line.** OpenCode does not scan installed packages for skills, so point it at the package's `skills/` directory yourself. `skills.paths` entries resolve against the project directory, so the package must be present in the project's `node_modules` - OpenCode's own plugin cache is not the same location:\n\n```bash\nnpm install --save-dev @dodopayments/opencode-plugin\n```\n\n```jsonc\n{\n    \"$schema\": \"https://opencode.ai/config.json\",\n    \"plugin\": [\"@dodopayments/opencode-plugin\"],\n    \"skills\": {\n        \"paths\": [\"node_modules/@dodopayments/opencode-plugin/skills\"]\n    }\n}\n```\n\nAn absolute path works too, and avoids the local-install requirement.\n\nVerify with `opencode run \"List every skill available to you by name.\"` - you should see all seventeen. A skills path that does not exist is ignored silently, so check rather than assume.\n\n> Versions before 0.5.0 documented these skills as auto-discovered. They were not: nothing in OpenCode scans an installed package, so OpenCode users had MCP servers but no skills. Setting `config.skills` from the plugin's `config` hook does not fix this either - the skill index is built before `config` hooks run, so it never registers anything.\n\nIf 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:\n\n```jsonc\n{\n    \"plugin\": [\"@dodopayments/opencode-plugin\"],\n    \"mcp\": {\n        \"dodopayments-api\": {\n            \"type\": \"local\",\n            \"command\": [\"npx\", \"-y\", \"dodopayments-mcp@latest\"],\n            \"environment\": {\n                \"DODO_PAYMENTS_API_KEY\": \"dodo_test_...\",\n                \"DODO_PAYMENTS_WEBHOOK_KEY\": \"whsec_...\",\n                \"DODO_PAYMENTS_ENVIRONMENT\": \"test_mode\"\n            },\n            \"enabled\": true\n        }\n    }\n}\n```\n\n## Included Skills\n\n**Getting started**\n\n| Skill | Description |\n|-------|-------------|\n| `dodo-best-practices` | SDK setup, environments, API keys, and the canonical checkout-to-webhook architecture |\n| `framework-adapters` | Official `@dodopayments/*` handlers for Next.js, Express, Hono, Astro, Remix, SvelteKit, Nuxt, Fastify, TanStack, Bun, Convex |\n| `testing-and-go-live` | Test mode, test payment methods, webhook testing, production launch checklist |\n\n**Accepting payments**\n\n| Skill | Description |\n|-------|-------------|\n| `checkout-integration` | Checkout Sessions, payment links, and overlay checkout |\n| `subscription-integration` | Subscription lifecycle, trials, plan changes, proration, on-demand charges |\n| `mobile-checkout` | In-app checkout for React Native, Flutter, iOS, and Android |\n| `webhook-integration` | Receiving and verifying webhooks via the Standard Webhooks spec |\n\n**Billing models**\n\n| Skill | Description |\n|-------|-------------|\n| `credit-based-billing` | Credit entitlements, balances, ledger, rollover, overage, meter-based deduction |\n| `usage-based-billing` | Meters, event ingestion, aggregation, and per-unit pricing |\n| `license-keys` | License key activation, validation, and instance management |\n\n**Catalog and pricing**\n\n| Skill | Description |\n|-------|-------------|\n| `product-catalog-management` | Products, pricing, add-ons, collections, images, digital delivery |\n| `discounts-and-promotions` | Discount codes, eligibility, stacking, subscription-cycle limits |\n| `localized-pricing` | Localized pricing, adaptive currency, and purchasing power parity |\n\n**Customers and operations**\n\n| Skill | Description |\n|-------|-------------|\n| `customer-management` | Customers, self-service portal, payment methods, wallets |\n| `refunds-and-disputes` | Refunds, disputes and chargebacks, access reconciliation |\n\n**UI and integrations**\n\n| Skill | Description |\n|-------|-------------|\n| `billing-sdk` | BillingSDK React components for pricing tables and billing UI |\n| `better-auth-integration` | The `@dodopayments/better-auth` plugin for customer sync, checkout, portal |\n\nSkills source: [`dodopayments/skills`](https://github.com/dodopayments/skills), vendored into `skills/` as real files. Provenance (upstream commit and applied transforms) is recorded in [`.skills-source.json`](./.skills-source.json).\n\n## Included MCP Servers\n\n| Server | Purpose | Auth |\n|--------|---------|------|\n| `dodopayments-api` | Live API access (payments, subscriptions, customers, products, refunds, licenses, usage) | OAuth (browser) |\n| `dodo-knowledge` | Semantic search over the Dodo Payments documentation | None |\n\nBoth servers speak Streamable HTTP. The canonical `mcp.json` declares them natively (`type: \"streamable-http\"`), which is what spec-native clients such as Codex CLI and Cursor use. The generated compatibility manifests — `.mcp.json`, read by Claude Code, VS Code and Cursor's legacy path — wire the same two endpoints through `mcp-remote` instead, so they run in clients that cannot yet dial Streamable HTTP directly.\n\n## Configure (optional, Claude Code)\n\nIf you prefer to run the API MCP locally with an API key instead of the remote server, open `/plugins` in Claude Code, select **Dodo Payments**, and choose **Configure options**. Fill in:\n\n- `dodo_api_key` - your `dodo_test_...` or `dodo_live_...` key\n- `dodo_webhook_key` - your webhook signing secret\n- `dodo_environment` - `test_mode` or `live_mode`\n\nThen edit `.mcp.json` to point `dodopayments-api` at the local stdio server:\n\n```json\n{\n    \"mcpServers\": {\n        \"dodopayments-api\": {\n            \"type\": \"stdio\",\n            \"command\": \"npx\",\n            \"args\": [\"-y\", \"dodopayments-mcp@latest\"],\n            \"env\": {\n                \"DODO_PAYMENTS_API_KEY\": \"${user_config.dodo_api_key}\",\n                \"DODO_PAYMENTS_WEBHOOK_KEY\": \"${user_config.dodo_webhook_key}\",\n                \"DODO_PAYMENTS_ENVIRONMENT\": \"${user_config.dodo_environment}\"\n            }\n        }\n    }\n}\n```\n\nRun `/reload-plugins` to apply changes to your current session.\n\n## Enable / disable individual MCP servers\n\nBoth MCPs ship enabled by default. You can turn either one off independently.\n\n### OpenCode\n\nThe npm plugin reads two environment variables before registering MCPs:\n\n| Env var | Effect |\n|---|---|\n| `DODO_DISABLE_API_MCP=1` | Skips registering `dodopayments-api` |\n| `DODO_DISABLE_KNOWLEDGE_MCP=1` | Skips registering `dodo-knowledge` |\n\nTruthy values: `1`, `true`, `yes`, `on` (case-insensitive). Export the var in your shell profile or set it inline:\n\n```bash\nDODO_DISABLE_API_MCP=1 opencode\n```\n\n### Claude Code, Codex CLI, Cursor\n\nThese 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`.\n\n**Claude Code** - edit `.mcp.json` at your project root (or run `claude mcp disable dodopayments-api`):\n\n```json\n{\n    \"mcpServers\": {\n        \"dodopayments-api\": {\n            \"type\": \"stdio\",\n            \"command\": \"npx\",\n            \"args\": [\"-y\", \"mcp-remote@latest\", \"https://mcp.dodopayments.com/mcp\"],\n            \"enabled\": false\n        }\n    }\n}\n```\n\nRun `/reload-plugins` to apply.\n\n**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.\n\n> 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.\n\n## A prompt to try first\n\nOnce the plugin is active, try:\n\n```\nSet up Dodo Payments webhook handlers in my Next.js app for payment.succeeded and subscription.active events.\n```\n\nYour 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.\n\n## Local development\n\n```bash\ngit clone https://github.com/dodopayments/dodo-agent-plugin.git\ncd dodo-agent-plugin\n```\n\nNo submodules, no build step - `skills/` is vendored as real files.\n\nValidate the Claude Code plugin and marketplace:\n\n```bash\nclaude plugin validate .\n```\n\nLoad the plugin directly for a dev session:\n\n```bash\nclaude --plugin-dir ./dodo-agent-plugin\n```\n\nVerify everything before pushing:\n\n```bash\nnpm run verify     # generated artifacts in sync + Agent Plugins conformance\n```\n\n### Repository layout\n\n| Path | Role |\n|---|---|\n| `plugin.json` | **Canonical.** Agent Plugins v1.0.0 manifest and the version source of truth |\n| `mcp.json` | **Canonical.** Agent Plugins v1.0.0 MCP config |\n| `skills/` | **Canonical.** Seventeen skills, vendored as real files |\n| `overlays/*.json` | Hand-authored provider extras the closed spec schema cannot express |\n| `.claude-plugin/`, `.cursor-plugin/`, `.agents/`, `.mcp.json`, `plugins/dodopayments/` | **Generated.** Do not hand-edit - run `npm run build` |\n| `scripts/build.mjs` | The single generator (`--check` for drift) |\n| `scripts/conformance.mjs` | Agent Plugins conformance validator |\n| `.skills-source.json` | Upstream provenance for the vendored skills |\n\nSkills are authored in [`dodopayments/skills`](https://github.com/dodopayments/skills) and vendored here. A weekly workflow re-syncs them and opens a PR; run it on demand with the **Sync skills from upstream** workflow dispatch.\n\n## For maintainers\n\nThe repo is configured to publish the OpenCode npm package on every GitHub Release.\n\n**One-time setup (already done for this repo):**\n\n- npm scope `@dodopayments` exists and is owned by Dodo Payments.\n- GitHub Actions secret `NPM_TOKEN` is provisioned with publish rights to the `@dodopayments` scope.\n\n**Release workflow:**\n\n1. Bump `version` in `plugin.json` (the single source of truth).\n2. Run `npm run build` to propagate it to every generated manifest.\n3. Run `npm run verify`, then commit and tag.\n4. Create a GitHub Release - the `Publish @dodopayments/opencode-plugin` workflow publishes to npm with provenance.\n\n**Manual dry-run:**\n\n- Workflow dispatch with `dry_run: true` to validate the release pipeline without publishing.\n\n**CI checks:**\n\n- `Verify` runs on every pull request and push to `main`: artifact drift, Agent Plugins conformance, live JSON Schema validation, a \"seventeen skills, zero symlinks\" assertion, and an npm payload check.\n- The release workflow re-runs the same gates before publishing.\n\n## Resources\n\n- [Dodo Payments documentation](https://docs.dodopayments.com)\n- [Agent Skills docs](https://docs.dodopayments.com/developer-resources/agent-skills)\n- [MCP Server docs](https://docs.dodopayments.com/developer-resources/mcp-server)\n- [Skills source repo](https://github.com/dodopayments/skills)\n- [Discord community](https://discord.gg/bYqAp4ayYh)\n\n## License\n\nMIT - see [LICENSE](./LICENSE).\n",
  "bytes": 16715,
  "sha": "007c15fe92523b42cb8a908a12ee817fe7efe082bafde7a2eebd2e2f8ee89c71",
  "repo_slug": "dodopayments/dodo-agent-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_dodopayments_dodo_agent_plugin_01107170/readme"
}