@dodopayments/opencode-plugin 0.6.4 → 0.7.0

package/README.md

@@ -42,7 +42,7 @@ claude plugins marketplace add dodopayments/dodo-agent-plugin
 claude plugins install dodopayments@dodopayments
 ```
 
-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.
+The API MCP server signs in with OAuth, so there is no API key to paste. The first time your agent calls a Dodo tool, a Dodo Payments consent page opens in your browser: pick the business, mode and permissions. See [Sign-in and access](#sign-in-and-access).
 
 ### Codex CLI
 
@@ -122,7 +122,7 @@ OpenCode distributes via npm. Add the plugin to your `opencode.json`:
 }
 ```
 
-Restart OpenCode. Both MCP servers (`dodopayments-api`, `dodo-knowledge`) are registered automatically via the plugin's `config` hook as native remote servers. No manual `mcp` block required. Run `opencode mcp auth dodopayments-api` to sign in to the API server.
+Restart OpenCode. Both MCP servers (`dodopayments-api`, `dodo-knowledge`) are registered automatically via the plugin's `config` hook as native remote servers. No manual `mcp` block required. Run `opencode mcp auth dodopayments-api` to open the Dodo Payments consent page for the API server.
 
 **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:
 
@@ -146,26 +146,6 @@ Verify with `opencode run "List every skill available to you by name."` - you sh
 
 > 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.
 
-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:
-
-```jsonc
-{
-    "plugin": ["@dodopayments/opencode-plugin"],
-    "mcp": {
-        "dodopayments-api": {
-            "type": "local",
-            "command": ["npx", "-y", "dodopayments-mcp@latest"],
-            "environment": {
-                "DODO_PAYMENTS_API_KEY": "dodo_test_...",
-                "DODO_PAYMENTS_WEBHOOK_KEY": "whsec_...",
-                "DODO_PAYMENTS_ENVIRONMENT": "test_mode"
-            },
-            "enabled": true
-        }
-    }
-}
-```
-
 ## Included Skills
 
 **Getting started**
@@ -227,34 +207,29 @@ Skills source: [`dodopayments/skills`](https://github.com/dodopayments/skills),
 
 Both servers speak Streamable HTTP over HTTPS, and every manifest dials them natively - no `npx mcp-remote` bridge and no Node dependency. The canonical `mcp.json` uses the spec's `type: "streamable-http"`; the generated `.mcp.json` (Claude Code, Cursor, VS Code, Grok Build, Devin, Goose, Droid) uses the same endpoints spelled `type: "http"`, the name that dialect uses; Muse, Antigravity, Junie and Gemini get their own spellings from the generator.
 
-## Configure (optional, Claude Code)
+## Sign-in and access
 
-If 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:
+The API MCP server signs in with OAuth. No config in this plugin holds an API key, and no step asks you to paste one.
 
-- `dodo_api_key` - your `dodo_test_...` or `dodo_live_...` key
-- `dodo_webhook_key` - your webhook signing secret
-- `dodo_environment` - `test_mode` or `live_mode`
+1. The first tool call on `dodopayments-api` opens a Dodo Payments consent page in your browser. Some clients start the sign-in from a command instead: `codex mcp login dodopayments-api`, `opencode mcp auth dodopayments-api`, `muse mcp login dodopayments-api`, or `/mcp` in Claude Code.
+2. Sign in, then pick the business, the mode (test or live) and the permissions to grant.
+3. The client stores the token. To switch to another business or mode, sign out of the server in your client and sign in again.
 
-Then edit `.mcp.json` to point `dodopayments-api` at the local stdio server:
+To review or revoke access, open the Dodo Payments dashboard at **Settings > Connected Apps**.
 
-```json
-{
-    "mcpServers": {
-        "dodopayments-api": {
-            "type": "stdio",
-            "command": "npx",
-            "args": ["-y", "dodopayments-mcp@latest"],
-            "env": {
-                "DODO_PAYMENTS_API_KEY": "${user_config.dodo_api_key}",
-                "DODO_PAYMENTS_WEBHOOK_KEY": "${user_config.dodo_webhook_key}",
-                "DODO_PAYMENTS_ENVIRONMENT": "${user_config.dodo_environment}"
-            }
-        }
-    }
-}
+Every client config in this repo dials `https://mcp.dodopayments.com/mcp` directly, sets no headers, and lets the client run OAuth discovery itself. A host that cannot run MCP OAuth gets `dodo-knowledge` only - today that is the xAI API (see [Grok](./docs/clients/grok.md)).
+
+### Dodo CLI
+
+The skills use the Dodo CLI for local webhook testing. It uses the same OAuth sign-in:
+
+```bash
+npm i -g dodopayments-cli   # browser sign-in needs v3.7.0 or later
+dodo login                  # sign in with the browser
+dodo whoami                 # show the stored sign-in
 ```
 
-Run `/reload-plugins` to apply changes to your current session.
+Over SSH or with no browser, run `dodo login --device` in place of `dodo login`, and enter the code on another device. To sign out when you finish, run `dodo logout all`.
 
 ## Enable / disable individual MCP servers
 

package/opencode-plugin/README.md

@@ -27,7 +27,7 @@ Restart OpenCode.
 - Both MCP servers are registered automatically via the plugin's `config` hook.
 - The `skills.paths` entry is what makes the skills visible - OpenCode does not scan installed packages for skills. The path resolves against the **project** directory, not OpenCode's plugin cache, which is why the local install above is required. An absolute path works too and avoids that requirement.
 - The plugin module exports only its default function. OpenCode's loader throws `Plugin export is not a function` on any non-function named export, skips the plugin, and swallows the error - leaving you with no MCP servers. Verified on OpenCode 1.18.15.
-- The first call to `dodopayments-api` opens a browser for OAuth. `dodo-knowledge` needs no auth.
+- The first call to `dodopayments-api` opens a Dodo Payments consent page in the browser: pick the business, mode and permissions. `opencode mcp auth dodopayments-api` starts the same sign-in. To review or revoke access, open the dashboard at **Settings > Connected Apps**. `dodo-knowledge` needs no auth.
 
 Verify the install:
 
@@ -67,26 +67,23 @@ Persist the toggle by exporting the var in your shell profile or a project `.env
 
 ## Overriding the defaults
 
-The plugin registers MCPs with nullish-assign semantics, so anything you declare in your own `opencode.json` wins. Example - swap the default remote OAuth server for the local stdio server with your own API key:
+The plugin registers MCPs with nullish-assign semantics, so anything you declare in your own `opencode.json` wins. Example - keep the API server declared but turned off:
 
 ```jsonc
 {
     "plugin": ["@dodopayments/opencode-plugin"],
     "mcp": {
         "dodopayments-api": {
-            "type": "local",
-            "command": ["npx", "-y", "dodopayments-mcp@latest"],
-            "environment": {
-                "DODO_PAYMENTS_API_KEY": "dodo_test_...",
-                "DODO_PAYMENTS_WEBHOOK_KEY": "whsec_...",
-                "DODO_PAYMENTS_ENVIRONMENT": "test_mode"
-            },
-            "enabled": true
+            "type": "remote",
+            "url": "https://mcp.dodopayments.com/mcp",
+            "enabled": false
         }
     }
 }
 ```
 
+The API server has no API key mode. Declare it only as the remote server above, which signs in with OAuth.
+
 `dodo-knowledge` continues to be registered by the plugin unless you declare it explicitly too.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dodopayments/opencode-plugin",
-    "version": "0.6.4",
+    "version": "0.7.0",
     "description": "Dodo Payments agent skills and MCP servers for OpenCode.",
     "type": "module",
     "main": "opencode-plugin/index.js",

package/skills/dodo-mcp-usage/SKILL.md

@@ -12,7 +12,7 @@ The [Dodo Payments agent plugin](https://github.com/dodopayments/dodo-agent-plug
 | Server | URL | Auth | Use it for |
 |--------|-----|------|------------|
 | `dodo-knowledge` | `https://knowledge.dodopayments.com/mcp` | None | Semantic search over Dodo Payments docs, API reference and SDK docs |
-| `dodopayments-api` | `https://mcp.dodopayments.com/mcp` | OAuth in the browser, or a local API key | Reading and changing real resources in your Dodo account |
+| `dodopayments-api` | `https://mcp.dodopayments.com/mcp` | OAuth: a Dodo Payments consent page in the browser | Reading and changing real resources in your Dodo account |
 
 ## When to call which
 
@@ -43,13 +43,13 @@ Don't use the API server to answer "how does X work" questions. That's what `dod
 
 The Dodo Payments MCP server uses **Code Mode**. Instead of one tool per endpoint, it exposes two tools:
 
-1. **Docs search**: query the API and SDK documentation.
+1. **Docs search** (`search_docs`): query the API and SDK documentation.
 2. **Code execution** (`execute`): write TypeScript against the `dodopayments` SDK. It runs in an isolated sandbox with no network or filesystem access, and whatever the code returns or prints comes back as the tool result.
 
 What this means for you:
 
 - Look at the tool list your client exposes for the exact tool names. Don't invent per-endpoint tool names like `create_product`; they don't exist in Code Mode.
-- The API key is injected server-side. You never pass a key in tool parameters, and you shouldn't try to read one from inside the sandbox.
+- The server authenticates every call with the user's OAuth sign-in. You never pass an API key or a token in tool parameters, and you shouldn't try to read one from inside the sandbox.
 - Batch related calls into one script and return only what you need (IDs, statuses, counts), not whole objects. One script with 20 calls beats 20 round trips.
 - Search docs (either server) for the SDK method shape before writing the script, then execute.
 
@@ -63,8 +63,8 @@ Typical read-only flow:
 
 These are non-negotiable when the API server is connected.
 
-1. **Default to test mode.** For the local server, `DODO_PAYMENTS_ENVIRONMENT` defaults to `live_mode` when unset, so set `test_mode` explicitly during development. Use `dodo_test_` keys with test mode and `dodo_live_` keys with live mode.
-2. **Know which mode you're in before any write.** With the local server, it is `DODO_PAYMENTS_ENVIRONMENT`. With the remote OAuth server the mode follows the account the user signed in to and is not visible in the tool configuration, so **always ask the user to confirm test or live mode before the first write in a session**. A read can help you check: for example, if the user gives an ID, retrieving it succeeds only in the mode it was created in.
+1. **Default to test mode.** The user picks the mode on the consent page when they sign in. During development, suggest test mode.
+2. **Know which mode you're in before any write.** The tool configuration does not show the mode the user picked on the consent page, so **always ask the user to confirm test or live mode before the first write in a session**. A read can help you check: for example, if the user gives an ID, retrieving it succeeds only in the mode it was created in.
 3. **Read before write.** Retrieve the resource first, show the user what will change, then act.
 4. **Confirm every live mode write with the user**, naming the exact resource ID and the effect. This is mandatory for:
    - refunds (full or partial),
@@ -72,71 +72,42 @@ These are non-negotiable when the API server is connected.
    - anything that moves money or affects payouts,
    - deleting or archiving products and discounts,
    - changing or deleting webhook endpoints.
-5. **Never print secrets.** Don't echo API keys, webhook signing keys, or full card or bank details into chat, logs, or files. Don't return them from `execute` scripts.
+5. **Never print secrets.** Don't echo API keys, OAuth tokens, webhook signing keys, or full card or bank details into chat, logs, or files. Don't return them from `execute` scripts.
 6. **Don't retry writes blindly.** If a create or refund call errors or times out, read the current state first (list refunds for the payment, fetch the subscription) before trying again, so you don't double-refund or create duplicates.
-7. **Least privilege.** Dodo API keys can be created with a read-only access level. For inspection-only work with the local server, suggest a read-only key.
+7. **Least privilege.** On the consent page, the user grants only the permissions the task needs. For inspection-only work, suggest read permissions only.
 
 ## Authentication
 
-### Remote server (recommended)
+The API server signs in with OAuth. No step asks for an API key.
 
-The plugin points at `https://mcp.dodopayments.com/mcp`. The first time a tool is called, the client opens a browser window to sign in to Dodo Payments. Finish sign-in there, then retry the call.
+The plugin points at `https://mcp.dodopayments.com/mcp`. The first tool call opens a Dodo Payments consent page in the browser. The user signs in and picks the business, the mode (test or live) and the permissions to grant, then you retry the call. The client stores the token, so later sessions don't ask again until it expires or is revoked.
+
+To review or revoke access, the user opens the Dodo Payments dashboard at **Settings > Connected Apps**. To switch to another business or mode, the user signs out of the server in the client and signs in again.
 
 Both servers speak Streamable HTTP, so clients connect to the URL directly (no bridge process). Client setup, if the user is wiring it up by hand:
 
 - **Claude Code**: `claude mcp add --transport http dodopayments-api https://mcp.dodopayments.com/mcp`
-- **Cursor and other `.mcp.json` clients**: `{"mcpServers": {"dodopayments-api": {"type": "http", "url": "https://mcp.dodopayments.com/mcp"}}}`
+- **Cursor** (`.cursor/mcp.json`): `{"mcpServers": {"dodopayments-api": {"url": "https://mcp.dodopayments.com/mcp"}}}`
+- **Other `.mcp.json` clients**: `{"mcpServers": {"dodopayments-api": {"type": "http", "url": "https://mcp.dodopayments.com/mcp"}}}`
 - **VS Code** (`.vscode/mcp.json` uses a top-level `servers` key): `{"servers": {"dodopayments-api": {"type": "http", "url": "https://mcp.dodopayments.com/mcp"}}}`
-- **Codex CLI**: `codex mcp add dodopayments-api --url https://mcp.dodopayments.com/mcp`, then `codex mcp login dodopayments-api`
+- **Codex CLI**: `codex mcp add dodopayments-api --url https://mcp.dodopayments.com/mcp`, then `codex mcp login dodopayments-api`. In `~/.codex/config.toml` this is a `[mcp_servers.dodopayments-api]` table with `url = "https://mcp.dodopayments.com/mcp"`.
+- **OpenCode** (`opencode.json`): `{"mcp": {"dodopayments-api": {"type": "remote", "url": "https://mcp.dodopayments.com/mcp"}}}`, then `opencode mcp auth dodopayments-api`
 - **Claude.ai**: Settings, Connectors, Add Custom Connector, paste the URL.
 
 `dodo-knowledge` is configured the same way with `https://knowledge.dodopayments.com/mcp` and needs no sign-in.
 
-For a client that cannot dial Streamable HTTP or run MCP OAuth itself, the `mcp-remote` bridge still works as a fallback: run `npx -y mcp-remote@latest https://mcp.dodopayments.com/mcp` as a stdio server.
-
-### Local stdio server
-
-Run the server on the user's machine with an API key:
-
-```json
-{
-  "mcpServers": {
-    "dodopayments_api": {
-      "command": "npx",
-      "args": ["-y", "dodopayments-mcp@latest"],
-      "env": {
-        "DODO_PAYMENTS_API_KEY": "dodo_test_...",
-        "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key",
-        "DODO_PAYMENTS_ENVIRONMENT": "test_mode"
-      }
-    }
-  }
-}
-```
-
-| Variable | Required | Notes |
-|----------|----------|-------|
-| `DODO_PAYMENTS_API_KEY` | Yes | From the dashboard, Developer, API Keys |
-| `DODO_PAYMENTS_WEBHOOK_KEY` | No | Webhook signing key |
-| `DODO_PAYMENTS_ENVIRONMENT` | No | `test_mode` or `live_mode`; defaults to `live_mode` |
-
-The local `execute` tool needs Deno on `PATH` (Deno 2.8 or earlier for now) and works on macOS and Linux only. On Windows, use WSL2 or the remote server. Docs search still works without Deno.
-
-Tell the user to keep the key in their client config or environment, never in a committed file.
+For a client that cannot dial Streamable HTTP or run MCP OAuth itself, the `mcp-remote` bridge still works as a fallback: run `npx -y mcp-remote@latest https://mcp.dodopayments.com/mcp` as a stdio server. It opens the same consent page.
 
 ## Troubleshooting
 
 **"Needs authentication" or 401 from the remote server**
-The OAuth sign-in hasn't happened or has expired. Ask the user to complete the browser sign-in and retry. If it keeps failing, sign out and back in from the client's MCP menu (for example `/mcp` in Claude Code, `codex mcp login`), then restart the client. Clients that still use the older `mcp-remote` bridge cache tokens in `~/.mcp-auth`; clearing that folder forces a fresh sign-in.
+The OAuth sign-in hasn't happened, has expired, or was revoked in Connected Apps. Ask the user to complete the consent page and retry. If it keeps failing, sign out and back in from the client's MCP menu (for example `/mcp` in Claude Code, `codex mcp login`), then restart the client. Clients that still use the older `mcp-remote` bridge cache tokens in `~/.mcp-auth`; clearing that folder forces a fresh sign-in.
 
-**Authentication errors with the local server**
-The key and environment don't match. A `dodo_test_` key needs `DODO_PAYMENTS_ENVIRONMENT=test_mode`; a `dodo_live_` key needs `live_mode`. If it still fails, have the user generate a new key in the dashboard.
+**A 403 or permission error on one call while other calls work**
+The permissions granted on the consent page don't cover that call, for example a refund without `refunds:write`. Ask the user to sign out of the server, sign in again, and grant the missing permission.
 
 **Empty lists or "not found" for an ID the user just gave you**
-You're probably in the wrong mode. Test mode and live mode data are fully separate. Confirm which mode the ID came from before concluding it doesn't exist.
-
-**`execute` errors locally but docs search works**
-Deno is missing, too new, or you're on Windows. See the local server notes above.
+You're probably in the wrong mode. Test mode and live mode data are fully separate. Confirm which mode the ID came from before concluding it doesn't exist. To change the mode, the user signs in again and picks the other mode on the consent page.
 
 **Tool execution failures**
 Read the API error in the result; it usually names the bad field. Re-check the method shape with `dodo-knowledge`, then fix the script. You can also have the user reproduce the call with curl against `https://test.dodopayments.com` to rule out the MCP layer.

package/skills/testing-and-go-live/SKILL.md

@@ -138,11 +138,14 @@ This immediately schedules the renewal. If you used the subscription-renewal-fai
 The CLI ships separately from the SDKs:
 
 ```bash
-npm install -g dodopayments-cli
-dodo login
+npm i -g dodopayments-cli   # browser sign-in needs v3.7.0 or later
+dodo login                  # sign in with the browser
+dodo whoami                 # show the stored sign-in
 ```
 
-`dodo login` opens the API Keys page, accepts a pasted key, and asks whether it is Test Mode or Live Mode. One key of each can stay authenticated at the same time.
+Over SSH or with no browser, run `dodo login --device` in place of `dodo login`, and enter the code on another device. To sign out when you finish, run `dodo logout all`.
+
+`dodo login` opens a Dodo Payments consent page: pick the business, mode and permissions. No step asks you to paste an API key. To review or revoke the CLI's access, open the dashboard at **Settings > Connected Apps**.
 
 ### Listen for webhooks locally
 
@@ -154,7 +157,7 @@ This forwards real test-mode events to your local URL over an outbound relay. It
 
 Two constraints to know before running it:
 
-- **A Test Mode key is required.** Live Mode keys are not supported by the listen flow.
+- **Test mode only.** The listen flow needs a test-mode sign-in. Live mode is not supported.
 - **The URL argument is required in direct mode.** Bare `dodo wh listen` only works inside the interactive TUI as `/wh listen`, which opens a wizard.
 
 Events arriving this way carry valid signatures, so verify them normally with `webhooks.unwrap()`.

package/skills/webhook-integration/references/local-testing.md

@@ -16,7 +16,7 @@ Forward real test-mode events to localhost:
 dodo wh listen http://localhost:3000/webhook
 ```
 
-This creates a test webhook, opens a WebSocket relay, and forwards events with the original `webhook-id`/`webhook-signature`/`webhook-timestamp` headers to your local URL. Requires a test-mode API key. The relay and CLI parse and **re-serialize** the JSON body, so if it differs byte-for-byte from the original (for example number formatting), signature verification fails even though the headers are intact - that is a relay artifact, not a bug in your verifier. The URL argument is required in direct mode — bare `dodo wh listen` only works as `/wh listen` inside the TUI.
+This creates a test webhook, opens a WebSocket relay, and forwards events with the original `webhook-id`/`webhook-signature`/`webhook-timestamp` headers to your local URL. Requires a test-mode sign-in with `dodo login` (`dodo login --device` over SSH). The relay and CLI parse and **re-serialize** the JSON body, so if it differs byte-for-byte from the original (for example number formatting), signature verification fails even though the headers are intact - that is a relay artifact, not a bug in your verifier. The URL argument is required in direct mode — bare `dodo wh listen` only works as `/wh listen` inside the TUI.
 
 ### CLI: Unsigned mock events