模型上下文协议 (MCP) 是一种开放标准,使 AI 应用能够安全地连接到外部数据源和 API。Dodo Payments MCP 服务器为像 Claude、Cursor 和其他兼容 MCP 的客户端提供结构化访问您的支付基础设施。
Dodo Payments MCP 服务器是使用 Stainless 构建的,并采用 Code Mode 架构,使 AI 代理能够在隔离的沙箱环境中编写和执行 TypeScript 代码,针对 Dodo Payments SDK。
关键功能
支付操作 :创建、检索和管理支付和退款
订阅管理 :处理定期账单、升级和取消
客户管理 :管理客户数据和门户访问
产品目录 :创建和更新产品、定价和折扣
许可证管理 :激活、验证和管理软件许可证
基于使用的计费 :跟踪和计费计量使用情况
Code Mode 的工作原理
Dodo Payments MCP 服务器使用 Code Mode,为您的 AI 代理提供两个强大的工具:
文档搜索工具 :查询有关 Dodo Payments API 和 SDK 的文档,以了解可用的操作和参数
代码执行工具 :编写针对 SDK 的 TypeScript 代码,该代码在没有网络或文件系统访问的安全沙箱环境中执行
这种架构使 AI 代理能够以确定性和可重复的方式执行复杂的多步骤支付操作。
使用 Code Mode,代理可以链式调用多个 API,处理条件逻辑,并执行计算——所有这些都在一次工具调用中完成。
选择最适合您工作流程的安装方法。
远程 MCP 服务器(推荐)
访问托管的 MCP 服务器,无需任何本地设置或安装。这是开始的最快方式。
配置您的 MCP 客户端
复制为您的特定客户端提供的 JSON 配置。对于 Cursor 或 Claude Desktop,将其添加到您的 MCP 设置中: {
"mcpServers" : {
"dodopayments_api" : {
"command" : "npx" ,
"args" : [ "-y" , "mcp-remote@latest" , "https://mcp.dodopayments.com/sse" ]
}
}
}
认证和配置
OAuth 流程将提示您:
输入您的 Dodo Payments API 密钥
选择您的环境(测试或生产)
选择您的 MCP 客户端类型
保持您的 API 密钥安全。在开发期间使用测试模式密钥。
完成设置
点击 登录并批准 以授权连接。 一旦连接,您的 AI 助手可以代表您与 Dodo Payments API 进行交互。
NPM 包
使用 NPM 本地安装和运行 MCP 服务器。
# Set your environment variables
export DODO_PAYMENTS_API_KEY = "dodo_test_..."
export DODO_PAYMENTS_WEBHOOK_KEY = "your_webhook_key"
export DODO_PAYMENTS_ENVIRONMENT = "live_mode"
# Run the latest version
npx -y dodopayments-mcp@latest
{
"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" : "live_mode"
}
}
}
}
使用 @latest 始终拉取最新版本,或固定到特定版本如 @1.0.0 以确保稳定性。
Docker
在容器化环境中运行 MCP 服务器以实现一致的部署。
# Pull the latest image
docker pull ghcr.io/dodopayments/mcp:latest
# Run the container
docker run -e DODO_PAYMENTS_API_KEY="dodo_test_..." \
-e DODO_PAYMENTS_WEBHOOK_KEY="your_webhook_key" \
-e DODO_PAYMENTS_ENVIRONMENT="live_mode" \
ghcr.io/dodopayments/mcp:latest
客户端配置
在您首选的 AI 客户端中配置 Dodo Payments MCP 服务器。
Cursor
Claude Desktop
Claude Code
VS Code
Cline (VS Code)
Zed
其他客户端
在 Cursor 中设置 Dodo Payments MCP 服务器,以启用对您的支付数据的对话访问。 一键安装 使用下面的按钮直接在 Cursor 中安装 MCP 服务器: [ ](https://cursor.com/en-US/install-mcp?name=dodopayments-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImRvZG9wYXltZW50cy1tY3AiXSwiZW52Ijp7IkRPRE9fUEFZTUVOVFNfQVBJX0tFWSI6IlNldCB5b3VyIERPRE9fUEFZTUVOVFNfQVBJX0tFWSBoZXJlLiIsIkRPRE9fUEFZTUVOVFNfV0VCSE9PS19LRVkiOiJTZXQgeW91ciBET0RPX1BBWU1FTlRTX1dFQkhPT0tfS0VZIGhlcmUuIn19 ) 点击后,在 Cursor 的 mcp.json 中设置您的环境变量,通过 Cursor 设置 > 工具与 MCP > 新建 MCP 服务器 。 手动配置
打开 Cursor 设置
导航到 Cursor 设置 > 功能 > 模型上下文协议 ,或按 Cmd/Ctrl + Shift + P 并搜索 “MCP 设置”。
编辑配置
点击 编辑配置 打开 mcp_config.json 文件。
添加 Dodo Payments 配置
选择以下配置之一: 远程服务器(推荐) {
"mcpServers" : {
"dodopayments" : {
"command" : "npx" ,
"args" : [ "-y" , "mcp-remote@latest" , "https://mcp.dodopayments.com/sse" ]
}
}
}
本地 NPX {
"mcpServers" : {
"dodopayments" : {
"command" : "npx" ,
"args" : [ "-y" , "dodopayments-mcp@latest" ],
"env" : {
"DODO_PAYMENTS_API_KEY" : "dodo_test_..." ,
"DODO_PAYMENTS_WEBHOOK_KEY" : "your_webhook_key"
}
}
}
}
保存并重启
保存配置文件并重启 Cursor。 通过询问 AI 助手您的 Dodo Payments 数据来验证连接。
在 Claude Desktop 中设置 Dodo Payments MCP 服务器,以启用对您的支付数据的对话访问。
找到配置文件
找到 Claude Desktop 配置文件:
macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Windows : %APPDATA%\Claude\claude_desktop_config.json
Linux : ~/.config/Claude/claude_desktop_config.json
编辑配置
在文本编辑器中打开文件并添加 Dodo Payments 配置: 远程服务器(推荐) {
"mcpServers" : {
"dodopayments" : {
"command" : "npx" ,
"args" : [ "-y" , "mcp-remote@latest" , "https://mcp.dodopayments.com/sse" ]
}
}
}
本地 NPX {
"mcpServers" : {
"dodopayments" : {
"command" : "npx" ,
"args" : [ "-y" , "dodopayments-mcp@latest" ],
"env" : {
"DODO_PAYMENTS_API_KEY" : "dodo_test_..." ,
"DODO_PAYMENTS_WEBHOOK_KEY" : "your_webhook_key"
}
}
}
}
重启 Claude Desktop
关闭并重新打开 Claude Desktop 以使更改生效。 在 Claude Desktop 中查找 🔌 图标以确认 MCP 服务器已连接。
在 Claude Code CLI 中设置 Dodo Payments MCP 服务器。 在终端中运行以下命令: claude mcp add --transport stdio dodopayments_api \
--env DODO_PAYMENTS_API_KEY="dodo_test_..." \
DODO_PAYMENTS_WEBHOOK_KEY="your_webhook_key" \
-- npx -y dodopayments-mcp
配置将存储在您主目录的 .claude.json 文件中。 Claude Code 会自动从您的 shell 中获取环境变量,因此您也可以在运行命令之前导出它们。
在 VS Code 中设置 Dodo Payments MCP 服务器。 一键安装 [打开 VS Code](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22dodopayments-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22dodopayments-mcp%22%5D%2C%22env%22%3A%7B%22DODO_PAYMENTS_API_KEY%22%3A%22在此设置您的 DODO_PAYMENTS_API_KEY。%22%2C%22DODO_PAYMENTS_WEBHOOK_KEY%22%3A%22在此设置您的 DODO_PAYMENTS_WEBHOOK_KEY。%22%7D%7D) 点击后,在 VS Code 的 mcp.json 中设置您的环境变量,通过 命令面板 > MCP:打开用户配置 。 手动配置
打开 MCP 配置
打开命令面板(Cmd/Ctrl + Shift + P)并搜索 “MCP:打开用户配置”。
添加服务器配置
添加 Dodo Payments MCP 服务器: {
"mcpServers" : {
"dodopayments" : {
"command" : "npx" ,
"args" : [ "-y" , "dodopayments-mcp@latest" ],
"env" : {
"DODO_PAYMENTS_API_KEY" : "dodo_test_..." ,
"DODO_PAYMENTS_WEBHOOK_KEY" : "your_webhook_key"
}
}
}
}
重新加载窗口
重新加载 VS Code (Cmd/Ctrl + Shift + P > “重新加载窗口”) 以激活 MCP 服务器。
在 Cline (VS Code) 中设置 Dodo Payments MCP 服务器,以启用对您的支付数据的对话访问。
打开 Cline 设置
找到 Cline 配置文件:
macOS : ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows : %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux : ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
配置 MCP 服务器
添加 Dodo Payments MCP 服务器配置: {
"mcpServers" : {
"dodopayments" : {
"command" : "npx" ,
"args" : [ "-y" , "dodopayments-mcp@latest" ],
"env" : {
"DODO_PAYMENTS_API_KEY" : "dodo_test_..." ,
"DODO_PAYMENTS_WEBHOOK_KEY" : "your_webhook_key"
}
}
}
}
重新加载 VS Code
重新加载 VS Code 窗口 (Cmd/Ctrl + Shift + P > “重新加载窗口”) 以激活 MCP 服务器连接。
在 Zed 中设置 Dodo Payments MCP 服务器,以启用对您的支付数据的对话访问。
打开 Zed 设置
导航到 设置 > 助手 > 模型上下文协议 。
添加服务器配置
添加以下配置: {
"mcpServers" : {
"dodopayments" : {
"command" : "npx" ,
"args" : [ "-y" , "dodopayments-mcp@latest" ],
"env" : {
"DODO_PAYMENTS_API_KEY" : "dodo_test_..." ,
"DODO_PAYMENTS_WEBHOOK_KEY" : "your_webhook_key"
}
}
}
}
保存并验证
保存配置。MCP 服务器现在应该在 Zed 的 AI 助手中可用。
在其他兼容 MCP 的客户端中设置 Dodo Payments MCP 服务器。 远程服务器(推荐) {
"mcpServers" : {
"dodopayments" : {
"command" : "npx" ,
"args" : [ "-y" , "mcp-remote@latest" , "https://mcp.dodopayments.com/sse" ]
}
}
}
本地 NPX {
"mcpServers" : {
"dodopayments" : {
"command" : "npx" ,
"args" : [ "-y" , "dodopayments-mcp@latest" ],
"env" : {
"DODO_PAYMENTS_API_KEY" : "dodo_test_..." ,
"DODO_PAYMENTS_WEBHOOK_KEY" : "your_webhook_key"
}
}
}
}
环境变量
使用环境变量配置 MCP 服务器的行为。
变量 描述 必需 DODO_PAYMENTS_API_KEY您的 Dodo Payments API 密钥 是 DODO_PAYMENTS_WEBHOOK_KEY您的 webhook 签名密钥 否 DODO_PAYMENTS_ENVIRONMENT设置为 live_mode 用于生产 否
远程运行
将 MCP 服务器作为远程 HTTP 服务器部署,以供基于 Web 的客户端或代理工作流使用。
# Start as remote server
npx -y dodopayments-mcp --transport=http
# Specify a custom port
npx -y dodopayments-mcp --transport=http --port=3000
远程服务器配置
部署后,客户端可以使用服务器 URL 连接:
{
"mcpServers" : {
"dodopayments_api" : {
"url" : "http://localhost:3000" ,
"headers" : {
"Authorization" : "Bearer your_api_key"
}
}
}
}
授权头
远程服务器接受通过以下头进行身份验证:
头 描述 AuthorizationBearer 令牌身份验证 x-dodo-payments-api-key直接 API 密钥头
客户端能力
不同的 MCP 客户端对 MCP 规范的支持程度不同。服务器可以自动调整工具架构以解决这些限制。
# Auto-detect client (default)
npx dodopayments-mcp --client=infer
# Configure for specific clients
npx dodopayments-mcp --client=cursor
npx dodopayments-mcp --client=claude
npx dodopayments-mcp --client=claude-code
npx dodopayments-mcp --client=openai-agents
可用客户端预设
客户端 描述 infer自动检测客户端(默认) cursorCursor 编辑器 claudeClaude AI 网页或桌面 claude-codeClaude Code CLI openai-agentsOpenAI 代理平台
手动能力配置
对于未列出的客户端,手动配置能力:
# Disable $ref pointer support and set max tool name length
npx dodopayments-mcp --no-capability=refs --capability=tool-name-length=40
可用能力:
top-level-unions - 支持顶级联合类型
valid-json - 正确的 JSON 字符串参数解析
refs - 支持架构中的 $ref 指针
unions - 支持联合类型(anyOf)
formats - 支持格式验证
tool-name-length=N - 最大工具名称长度
运行 npx dodopayments-mcp --describe-capabilities 获取详细的能力信息。
工具过滤
控制哪些 API 操作暴露给您的 AI 助手,以优化性能并维护安全性。
按操作类型过滤
限制访问只读或写操作。
# Only expose read operations (GET requests)
npx dodopayments-mcp --operation=read
# Only expose write operations (POST, PUT, DELETE)
npx dodopayments-mcp --operation=write
在开发期间使用 --operation=read 以防止意外修改您的数据。
按资源过滤
限制工具到特定的 API 资源。
# Only expose payment-related tools
npx dodopayments-mcp --resource=payments
# Expose multiple resources
npx dodopayments-mcp --resource=payments --resource=customers
# Use wildcards for resource groups
npx dodopayments-mcp --resource=subscription *
包含或排除特定工具
微调可用的单个工具。
# Include only specific tools
npx dodopayments-mcp --tool=create_payments --tool=list_payments
# Exclude specific tools
npx dodopayments-mcp --no-tool=delete_products
# Disable the docs search tool
npx dodopayments-mcp --no-tools=docs
# List all available tools
npx dodopayments-mcp --list
组合过滤器
同时应用多个过滤器以实现精确控制。
# Only payment and subscription read operations
npx dodopayments-mcp --operation=read --resource=payments --resource=subscriptions
URL 查询参数过滤(远程服务器)
使用远程服务器时,通过 URL 查询参数应用过滤器:
https://mcp.dodopayments.com/?operation=read
https://mcp.dodopayments.com/?resource=payments
动态工具模式
对于大型 API,一次加载所有工具可能会使 AI 的上下文窗口不堪重负。动态工具模式提供了更高效的替代方案。
npx dodopayments-mcp --tools=dynamic
在动态模式下,三个元工具替代单个 API 工具:
list_api_endpoints - 发现可用的方法并可选过滤
get_api_endpoint_schema - 获取特定方法的详细架构
invoke_api_endpoint - 执行任何方法并提供适当的参数
对于具有超过 50 个方法的 API,动态工具会自动启用。使用 --tools=all 覆盖以包含所有工具。
# Use both dynamic tools and specific resources
npx dodopayments-mcp --tools=dynamic --resource=payments
高级用法
程序化集成
构建自定义 MCP 服务器或以编程方式扩展现有服务器。
import { server , endpoints , init } from "dodopayments-mcp/server" ;
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js" ;
// Initialize with all default endpoints
init ({ server , endpoints });
// Start the server
const transport = new StdioServerTransport ();
await server . connect ( transport );
自定义工具开发
使用您自己的工具和业务逻辑扩展 MCP 服务器。
import { server , init } from "dodopayments-mcp/server" ;
import createPayments from "dodopayments-mcp/tools/payments/create-payments" ;
import { zodToJsonSchema } from "zod-to-json-schema" ;
import { z } from "zod" ;
// Define a custom tool
const customTool = {
tool: {
name: 'calculate_payment_total' ,
description: 'Calculate payment total with tax and fees' ,
inputSchema: zodToJsonSchema (
z . object ({
amount: z . number (). describe ( 'Base amount in cents' ),
tax_rate: z . number (). describe ( 'Tax rate as decimal' ),
})
),
},
handler : async ( client , args ) => {
const total = args . amount * ( 1 + args . tax_rate );
return {
content: [{
type: 'text' ,
text: JSON . stringify ({ total , currency: 'usd' }),
}],
};
},
};
// Initialize with custom tools
init ({
server ,
endpoints: [ createPayments , customTool ]
});
安全最佳实践
保护您的 API 凭据并维护安全集成。
绝不要将凭据提交到版本控制 将 API 密钥存储在环境变量或安全的秘密管理系统中。 # Use environment variables
export DODO_PAYMENTS_API_KEY = "dodo_test_..."
# Use a .env file (add to .gitignore)
echo "DODO_PAYMENTS_API_KEY=dodo_test_..." > .env
定期轮换密钥 定期生成新的 API 密钥,并通过您的 Dodo Payments 仪表板撤销旧密钥。 在开发中使用测试密钥 在开发期间始终使用测试模式 API 密钥,以避免影响生产数据。
在生产中应用工具过滤 限制暴露的操作仅限于您的 AI 助手所需的操作。 # Production: read-only access
npx dodopayments-mcp --operation=read
# Development: full access
npx dodopayments-mcp
为远程服务器实施身份验证 在远程部署时,始终要求通过 Authorization 头或 x-dodo-payments-api-key 头进行身份验证。 监控 API 使用情况 通过您的 Dodo Payments 仪表板跟踪 MCP 服务器活动,并为异常模式设置警报。
为远程服务器使用 HTTPS 始终在 HTTPS 端点后面部署远程 MCP 服务器。 实施速率限制 通过在 MCP 服务器和 API 级别实施速率限制来防止滥用。 限制网络访问 配置防火墙规则以限制可以连接到您的 MCP 服务器的客户端。
故障排除
验证您的 API 密钥 确保您的 API 密钥设置正确并具有必要的权限。 # Test your API key
curl -H "Authorization: Bearer dodo_test_..." \
https://api.dodopayments.com/payments
检查您的网络连接 验证您可以访问 Dodo Payments API 端点。 查看客户端日志 在您的 MCP 客户端中启用详细日志记录以诊断连接问题。
确认 API 密钥环境 确保您在测试端点使用测试密钥,在生产端点使用生产密钥。 检查环境变量 验证 DODO_PAYMENTS_ENVIRONMENT 是否设置正确(live_mode 用于生产)。 重新生成凭据 如果问题仍然存在,请通过您的仪表板生成新的 API 密钥。
验证输入参数 确保 AI 助手提供每个工具的正确格式参数。 查看错误消息 检查 API 的错误响应以获取有关出错的具体指导。 直接测试 API 验证在通过 curl 或 Postman 直接调用 Dodo Payments API 时操作是否有效。
尝试不同的客户端预设 如果工具无法正常工作,请尝试明确指定您的客户端: npx dodopayments-mcp --client=cursor
检查能力支持 某些客户端不支持所有 JSON 架构特性。使用 --describe-capabilities 了解支持的内容。