MCP server

这是什么

payzu-mcp-pix 是一个本地 MCP 服务器。它通过 npx 在你的机器上运行,并以 stdio 与 AI 助手通信。也提供托管版本(见下文"托管服务器(免安装)"一节),无需安装任何东西。无论哪种方式,助手决定调用哪个 tool,服务器用你的 token 向 Pix Processamento API 发起 HTTP 调用。

MCP 是一个开放协议,让 AI 助手通过 JSON-RPC 调用外部工具。当你希望助手在开发或交互式使用中对账户执行真实操作时,用 MCP。如果目标是让你的生产应用与 PayZu 通信,请用 SDK(payzu-pix)。

开始之前

在 abrirconta.payzu.com.br 获取 API token:

1. 登录你的账户。
2. 打开凭证区域(API token 部分)。
3. 复制 token。该值填入 PAYZU_TOKEN。

托管服务器（免安装）

不想安装任何东西？将任何兼容的 MCP 客户端指向托管服务器：

https://mcp.payzu.com.br/mcp

• claude.ai 和 Claude Desktop：设置 → 连接器 → 添加自定义连接器 → 粘贴 URL。PayZu 页面会打开，只需输入一次令牌（OAuth）；助手永远不会看到或存储令牌。
• Cursor / VS Code：一键安装：

• Claude Code：claude mcp add --transport http payzu-pix https://mcp.payzu.com.br/mcp（首次使用时打开授权流程）。无 OAuth 替代方案：通过 Authorization 头发送 API Bearer 令牌：--header "Authorization: Bearer <your-token>"。
• Claude Desktop（本地安装包）：下载 payzu-mcp-pix.mcpb 并打开文件；Claude 只会要求输入令牌。

托管服务器是无状态的：不存储令牌或账户数据。每个请求都使用您的凭证转发到 Pix Processamento API，与直接调用完全相同。

Google Antigravity

在 Antigravity 界面中:

1. 在 agent 面板(Agent Manager)顶部点击 ... 菜单。
2. 选择 MCP Servers,再选 Manage MCP Servers。
3. 点击 View raw config。
4. 粘贴下面的配置,并替换成你的 token:

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": { "PAYZU_TOKEN": "your-token-here" }
    }
  }
}

配置文件位置:

• 新版本(Antigravity 2.0):~/.gemini/config/mcp_config.json。
• 早期构建:~/.gemini/antigravity/mcp_config.json。

保存后在 Manage MCP Servers 界面点击 Refresh。

Claude Code

claude mcp add payzu-pix --env PAYZU_TOKEN=your-token -- npx -y payzu-mcp-pix

用 --scope user 让该服务器在所有项目生效:

claude mcp add payzu-pix --scope user --env PAYZU_TOKEN=your-token -- npx -y payzu-mcp-pix

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json(macOS)或 %APPDATA%\Claude\claude_desktop_config.json(Windows):

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": { "PAYZU_TOKEN": "your-token-here" }
    }
  }
}

保存后重启 Claude Desktop。

Cursor

编辑项目里的 .cursor/mcp.json,或全局 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": { "PAYZU_TOKEN": "your-token-here" }
    }
  }
}

VS Code (GitHub Copilot)

编辑 .vscode/mcp.json。这里的键是 servers(不是 mcpServers),type 设为 stdio。用 inputs 配合 promptString 和 password,让 token 不被提交:

{
  "servers": {
    "payzu-pix": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": { "PAYZU_TOKEN": "${input:payzu-token}" }
    }
  },
  "inputs": [
    {
      "id": "payzu-token",
      "type": "promptString",
      "description": "PayZu API token",
      "password": true
    }
  ]
}

Windsurf

编辑 ~/.codeium/windsurf/mcp_config.json,同样的 mcpServers 结构:

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": { "PAYZU_TOKEN": "your-token-here" }
    }
  }
}

使用步骤

1. 在 abrirconta.payzu.com.br 获取 token。
2. 用上面某个配置块设置你的客户端(Antigravity、Claude Code、Claude Desktop、Cursor、VS Code 或 Windsurf)。
3. 用自然语言请求一笔收款,例如:

"创建一笔 R$ 50,00 的 Pix 收款,reference 为 pedido-001,callback 为 https://meusite.com.br/webhook"

4. agent 调用 pix_create,返回收款的 id 和 qrCodeText。
5. 问"我的余额是多少?",agent 调用 account_balance 并返回数字。

不生效?

• 错误 [401]:token 无效或已过期。在 abrirconta.payzu.com.br 生成新的。
• tool 列表里没有该服务器:重新加载或重启客户端(Antigravity 用 Refresh)。

tools 清单(48 个)

所有名称采用 snake_case。每个 tool 的 description 包含直达文档对应 endpoint 页面的链接。

Pix 收款(4)

Pix 付款(6)

退款(1)

Webhooks(8)

内部转账(2)

账户(3)

报表(11)

callbacks(8)

MED 违规(5)

¹ 在托管服务器上被禁用,原因见上方警告:它们以 stub 形式注册,只会回复该操作不可用。在本地应用(npx payzu-mcp-pix 或 .mcpb 安装包)中可正常使用。

默认约定

• 金额一律使用雷亚尔小数,绝不用分:R$ 99,90 写作 99.90。
• 创建类调用必须传 clientReference(幂等)。
• 创建类调用的 callbackUrl 是可选的。不传则该交易没有单独的投递;已注册的 webhook 仍会收到事件,状态也可以用查询 tool 获取。
• 仅对读取类请求(GET、HEAD、OPTIONS)且仅在 408、429、500、502、503、504 状态下自动重试,采用指数退避 + jitter,最多重试 3 次。创建类调用永不重试:失败的 POST 不会变成重复收款。
• 错误信息包含 requestId,如需协助直接复制给支持团队。
• 零 admin endpoints,仅暴露公开与客户端层面。

环境变量

支持