MCP server

这是什么

payzu-mcp-pix 是一个本地 MCP 服务器。它通过 npx 在你的机器上运行,并以 stdio 与 AI 助手通信。它不是托管服务器,也没有 URL:助手决定调用哪个 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。

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 清单(29 个)

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

Pix 收款(4)

提现(6)

内部转账(2)

账户(2)

报表(6)

callbacks(4)

MED 违规(5)

默认约定

• 金额以雷亚尔小数形式传入。tool 拒绝分单位:9990 会触发校验错误,必须是 99.90。
• 创建类调用必须传 clientReference(幂等)。
• 创建类调用必须传 callbackUrl,否则没人通知你状态。
• 5xx/429 自动重试,采用指数退避 + jitter(最多 3 次)。
• 错误信息包含 requestId,如需协助直接复制给支持团队。
• 零 admin endpoints,仅暴露公开与客户端层面。

环境变量

支持