用途
Dodo Payments 的智能体插件内置两个 MCP 服务器,本技能用于说明它们各自做什么、什么时候该调用哪一个,以及如何安全使用。
前提:只有在服务器已连接时本技能才有用。单独安装这些技能(例如使用 npx skills add)并不会连接服务器。请检查工具列表中是否存在 Dodo 工具;如果没有,请安装智能体插件(它会注册两个服务器),或按“身份认证”部分手动添加。没有服务器时,退回到其他技能和 docs.dodopayments.com 的文档。
两个服务器
| 服务器 | URL | 认证 | 用途 |
|---|---|---|---|
| dodo-knowledge | https://knowledge.dodopayments.com/mcp | 无 | 对 Dodo Payments 文档、API 参考和 SDK 文档做语义搜索 |
| dodopayments-api | https://mcp.dodopayments.com/mcp | 浏览器 OAuth,或本地 API key | 读取和修改 Dodo 账户中的真实资源 |
何时调用哪一个
先调 dodo-knowledge,再写集成代码:你对 Dodo API 的记忆可能已经过时。以下情况应搜索文档:请求与响应结构(例如结账会话字段、订阅计划变更参数);webhook 事件名称与负载字段;SDK 方法名以及哪些端点已弃用;基础 URL(测试模式 https://test.dodopayments.com,实时模式 https://live.dodopayments.com)。文档结果优先于你的记忆;两者冲突时以文档为准。查询中带上框架或语言可获得更精确的结果,例如 "Next.js webhook handler verify signature"。
调 dodopayments-api 对真实数据执行操作:当任务需要用户的实际账户时使用,包括列出或创建产品与价格;创建结账会话以端到端测试流程;按 ID 查询客户、支付或订阅;查看或注册 webhook 端点;发起退款或取消订阅(仅在确认之后,见“安全规则”)。不要用 API 服务器回答“X 如何工作”这类问题,那是 dodo-knowledge 的职责。
API 服务器的工作方式:Code Mode
该 MCP 服务器使用 Code Mode,不是每个端点一个工具,而是暴露两个工具:
- 文档搜索:查询 API 与 SDK 文档。
- 代码执行(execute):针对 dodopayments SDK 编写 TypeScript。代码在隔离沙箱中运行,无网络和文件系统访问,代码返回或打印的内容作为工具结果返回。
对你的含义:查看客户端暴露的工具列表以获得确切的工具名;不要臆造 create_product 之类按端点命名的工具,Code Mode 中不存在。API key 由服务器端注入,你永远不要在工具参数中传 key,也不应尝试在沙箱中读取。把相关调用合并到一个脚本中,只返回需要的内容(ID、状态、计数),而不是整个对象;一个含 20 次调用的脚本胜过 20 次往返。写脚本前先(在任一服务器上)搜索文档确认 SDK 方法形态,然后执行。
典型的只读流程:搜索文档中的方法,例如 "list subscriptions for a customer";运行一段简短的 execute 脚本调用它并返回精简摘要;把结果报告给用户。
安全规则
API 服务器连接时这些规则不可协商:
- 默认使用测试模式。对本地服务器,DODO_PAYMENTS_ENVIRONMENT 未设置时默认为 live_mode,因此开发期间应显式设置为 test_mode。dodo_test_ 密钥配测试模式,dodo_live_ 密钥配实时模式。
- 任何写入前先确认自己处于哪种模式。本地服务器看 DODO_PAYMENTS_ENVIRONMENT;远程 OAuth 服务器的模式跟随用户登录的账户,在工具配置中不可见,因此每次会话的第一次写入前都应让用户确认是测试还是实时模式。读取可以帮助判断:例如用户给出 ID,只有在其创建时所在的模式下才能检索成功。
- 先读后写。先检索资源,向用户展示将要发生的变化,然后再操作。
- 每一次实时模式写入都要与用户确认,并说明确切的资源 ID 和影响。以下操作强制要求确认:退款(全额或部分);订阅取消与计划变更;任何涉及资金流转或影响打款的操作;删除或归档产品与折扣;修改或删除 webhook 端点。
- 绝不打印密钥。不要把 API key、webhook 签名密钥或完整卡号、银行信息回显到聊天、日志或文件中,也不要在 execute 脚本中返回它们。
- 不要盲目重试写入。如果创建或退款调用报错或超时,先读取当前状态(列出该支付的退款、获取订阅),再决定是否重试,以免重复退款或产生重复数据。
- 最小权限。Dodo API key 可以创建为只读访问级别;对本地服务器做仅检查类工作时,建议使用只读 key。
身份认证
远程服务器(推荐)
插件指向 https://mcp.dodopayments.com/mcp。首次调用工具时,客户端会打开浏览器窗口登录 Dodo Payments,完成登录后重试调用。
两个服务器都使用 Streamable HTTP,客户端直接连接 URL(无需桥接进程)。手工接入时:
- Claude Code:claude mcp add --transport http dodopayments-api https://mcp.dodopayments.com/mcp
- Cursor 及其他 .mcp.json 客户端:{"mcpServers": {"dodopayments-api": {"type": "http", "url": "https://mcp.dodopayments.com/mcp"}}}
- VS Code(.vscode/mcp.json 使用顶层 servers 键):{"servers": {"dodopayments-api": {"type": "http", "url": "https://mcp.dodopayments.com/mcp"}}}
- Codex CLI:codex mcp add dodopayments-api --url https://mcp.dodopayments.com/mcp,然后 codex mcp login dodopayments-api
- Claude.ai:Settings、Connectors、Add Custom Connector,粘贴 URL。
配置 dodo-knowledge 的方式相同,URL 为 https://knowledge.dodopayments.com/mcp,且无需登录。
对于无法直接使用 Streamable HTTP 或自行执行 MCP OAuth 的客户端,mcp-remote 桥接仍可作为后备方案:以 stdio 服务器方式运行 npx -y mcp-remote@latest https://mcp.dodopayments.com/mcp。
本地 stdio 服务器
在用户机器上使用 API key 运行服务器:
{
"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"
}
}
}
}
变量说明:
- DODO_PAYMENTS_API_KEY:必需,来自控制台的 Developer、API Keys。
- DODO_PAYMENTS_WEBHOOK_KEY:可选,webhook 签名密钥。
- DODO_PAYMENTS_ENVIRONMENT:可选,test_mode 或 live_mode,默认 live_mode。
本地 execute 工具需要 PATH 中存在 Deno(目前为 Deno 2.8 或更早版本),且仅支持 macOS 和 Linux。Windows 上请使用 WSL2 或远程服务器。没有 Deno 时文档搜索仍可用。
请告知用户把 key 保存在客户端配置或环境变量中,绝不要放在会被提交的文件里。
故障排查
- 远程服务器提示“需要认证”或返回 401:OAuth 登录尚未完成或已过期。请用户完成浏览器登录后重试。若持续失败,从客户端的 MCP 菜单登出再登录(例如 Claude Code 的 /mcp、codex mcp login),然后重启客户端。仍在使用旧版 mcp-remote 桥接的客户端会把令牌缓存在 ~/.mcp-auth,清空该目录可强制重新登录。
- 本地服务器认证错误:key 与环境不匹配。dodo_test_ key 需要 DODO_PAYMENTS_ENVIRONMENT=test_mode,dodo_live_ key 需要 live_mode。若仍失败,请用户在控制台生成新 key。
- 用户刚给出的 ID 出现空列表或“未找到”:很可能处于错误的模式。测试模式与实时模式数据完全隔离,先确认该 ID 来自哪种模式,再断定其不存在。
- 本地 execute 报错但文档搜索正常:缺少 Deno、Deno 版本过新,或运行在 Windows 上。参见上文本地服务器说明。
- 工具执行失败:读取结果中的 API 错误,通常它会指出出错字段。用 dodo-knowledge 重新核对方法形态,然后修正脚本。也可以让用户用 curl 对 https://test.dodopayments.com 复现该调用,以排除 MCP 层问题。
- 限流(429):放慢速度,把工作合并到更少的脚本中,重试前先退避。不要对写入操作做循环重试。
相关技能
- checkout-integration:在应用代码中构建结账会话。
- webhook-integration:校验与处理 webhook 事件。
- testing-and-go-live:安全地从测试模式迁移到实时模式。
- dodo-best-practices:整体集成指导。