# MCP server (/zh/docs/pix-processamento/mcp)
## 这是什么 [#这是什么]
`payzu-mcp-pix` 是一个本地 MCP 服务器。它通过 `npx` 在你的机器上运行,并以 stdio 与 AI 助手通信。也提供托管版本(见下文"托管服务器(免安装)"一节),无需安装任何东西。无论哪种方式,助手决定调用哪个 tool,服务器用你的 token 向 Pix Processamento API 发起 HTTP 调用。
[MCP](https://modelcontextprotocol.io) 是一个开放协议,让 AI 助手通过 JSON-RPC 调用外部工具。当你希望助手在开发或交互式使用中对账户执行真实操作时,用 MCP。如果目标是让你的生产应用与 PayZu 通信,请用 [SDK](/docs/pix-processamento/sdks)(`payzu-pix`)。
需要 `payzu-mcp-pix` 0.3.0 或更高版本,以及 Node 20 或更高版本。
## 开始之前 [#开始之前]
在 [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br) 获取 API token:
1. 登录你的账户。
2. 打开凭证区域(API token 部分)。
3. 复制 token。该值填入 `PAYZU_TOKEN`。
token 拥有账户的真实访问权限:创建收款、Pix 付款和查看余额。请像密码一样对待。建议在每个 agent 操作执行前先批准,而不是让它无人值守地运行。
## 托管服务器（免安装） [#托管服务器免安装]
不想安装任何东西？将任何兼容的 MCP 客户端指向托管服务器：
```
https://mcp.payzu.com.br/mcp
```
* **claude.ai 和 Claude Desktop**：设置 → 连接器 → *添加自定义连接器* → 粘贴 URL。PayZu 页面会打开，只需输入一次令牌（OAuth）；助手永远不会看到或存储令牌。
* **Cursor / VS Code**：一键安装：
[](https://cursor.com/en/install-mcp?name=payzu-pix\&config=eyJ1cmwiOiJodHRwczovL21jcC5wYXl6dS5jb20uYnIvbWNwIn0%3D)
[](https://insiders.vscode.dev/redirect/mcp/install?name=payzu-pix\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.payzu.com.br%2Fmcp%22%7D)
* **Claude Code**：`claude mcp add --transport http payzu-pix https://mcp.payzu.com.br/mcp`（首次使用时打开授权流程）。无 OAuth 替代方案：通过 `Authorization` 头发送 API Bearer 令牌：`--header "Authorization: Bearer "`。
* **Claude Desktop（本地安装包）**：下载 [payzu-mcp-pix.mcpb](https://github.com/PayZuAI/payzu-mcp/releases/latest) 并打开文件；Claude 只会要求输入令牌。
托管服务器是无状态的：不存储令牌或账户数据。每个请求都使用您的凭证转发到 Pix Processamento API，与直接调用完全相同。
**提现和转账在托管服务器上不可用。** 这些操作依赖于您账户的 IP 白名单，而托管服务器是共享的（所有人共用一个 IP）。要通过 AI 提现，请使用**本地应用**（`npx payzu-mcp-pix` 或 `.mcpb` 安装包），它从您自己的 IP 运行；或直接在仪表板中提现。查询、余额和创建收款在托管服务器上正常工作。
## Google Antigravity [#google-antigravity]
在 Antigravity 界面中:
1. 在 agent 面板(Agent Manager)顶部点击 `...` 菜单。
2. 选择 `MCP Servers`,再选 `Manage MCP Servers`。
3. 点击 `View raw config`。
4. 粘贴下面的配置,并替换成你的 token:
```json
{
"mcpServers": {
"payzu-pix": {
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "your-token-here" }
}
}
}
```
把 token 原样粘贴进 `env`。变量展开 `${VAR}` 在某些版本会失败。
配置文件位置:
* 新版本(Antigravity 2.0):`~/.gemini/config/mcp_config.json`。
* 早期构建:`~/.gemini/antigravity/mcp_config.json`。
保存后在 `Manage MCP Servers` 界面点击 `Refresh`。
Antigravity 需要 `payzu-mcp-pix` 0.3.0 或更高版本。旧版本中带点的 tool 名称会被 Antigravity 使用的模型(Gemini、Claude、GPT)拒绝。
## Claude Code [#claude-code]
```bash
claude mcp add payzu-pix --env PAYZU_TOKEN=your-token -- npx -y payzu-mcp-pix
```
用 `--scope user` 让该服务器在所有项目生效:
```bash
claude mcp add payzu-pix --scope user --env PAYZU_TOKEN=your-token -- npx -y payzu-mcp-pix
```
## Claude Desktop [#claude-desktop]
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`(macOS)或 `%APPDATA%\Claude\claude_desktop_config.json`(Windows):
```json
{
"mcpServers": {
"payzu-pix": {
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "your-token-here" }
}
}
}
```
保存后重启 Claude Desktop。
## Cursor [#cursor]
编辑项目里的 `.cursor/mcp.json`,或全局 `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"payzu-pix": {
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "your-token-here" }
}
}
}
```
## VS Code (GitHub Copilot) [#vs-code-github-copilot]
编辑 `.vscode/mcp.json`。这里的键是 `servers`(不是 `mcpServers`),`type` 设为 `stdio`。用 `inputs` 配合 `promptString` 和 `password`,让 token 不被提交:
```json
{
"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 [#windsurf]
编辑 `~/.codeium/windsurf/mcp_config.json`,同样的 `mcpServers` 结构:
```json
{
"mcpServers": {
"payzu-pix": {
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "your-token-here" }
}
}
}
```
## 使用步骤 [#使用步骤]
1. 在 [abrirconta.payzu.com.br](https://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](https://meusite.com.br/webhook)"
4. agent 调用 `pix_create`,返回收款的 `id` 和 `qrCodeText`。
5. 问"我的余额是多少?",agent 调用 `account_balance` 并返回数字。
### 不生效? [#不生效]
* 错误 `[401]`:token 无效或已过期。在 [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br) 生成新的。
* tool 列表里没有该服务器:重新加载或重启客户端(Antigravity 用 `Refresh`)。
## tools 清单(29 个) [#tools-清单29-个]
所有名称采用 snake\_case。每个 tool 的 `description` 包含直达文档对应 endpoint 页面的链接。
### Pix 收款(4) [#pix-收款4]
| Tool | HTTP |
| ------------- | ---------------------------------- |
| `pix_create` | `POST /pix` |
| `pix_get` | `GET /pix` |
| `pix_qr_code` | `GET /pix/qr-code/{transactionId}` |
| `pix_proof` | `GET /proof/{id}` |
### Pix 付款(6) [#pix-付款6]
| Tool | HTTP |
| ------------------ | --------------------------- |
| `withdraw_create` | `POST /withdraw` |
| `withdraw_get` | `GET /withdraw` |
| `withdraw_by_qr` | `POST /withdraw/qrcode` |
| `withdraw_read_qr` | `POST /pix/qrcode/read` |
| `withdraw_dict` | `GET /pix/key?pixKey={key}` |
| `withdraw_proof` | `GET /withdraw/proof/{id}` |
### 内部转账(2) [#内部转账2]
| Tool | HTTP |
| -------------------------- | ------------------------- |
| `internal_transfer_create` | `POST /internal-transfer` |
| `internal_transfer_get` | `GET /internal-transfer` |
### 账户(2) [#账户2]
| Tool | HTTP |
| ----------------- | ------------------- |
| `account_profile` | `GET /user` |
| `account_balance` | `GET /user/balance` |
### 报表(6) [#报表6]
| Tool | HTTP |
| --------------------------- | --------------------------------- |
| `reports_list_transactions` | `GET /user/transactions` |
| `reports_get_transaction` | `GET /user/transactions/{id}` |
| `reports_create_csv` | `POST /user/report` |
| `reports_list_jobs` | `GET /user/report` |
| `reports_get_job` | `GET /user/report/{id}` |
| `reports_download` | `POST /user/report/{id}/download` |
### callbacks(4) [#callbacks4]
| Tool | HTTP |
| ----------------------- | --------------------------------------------- |
| `callbacks_list` | `GET /user/callbacks` |
| `callbacks_get` | `GET /user/callbacks/{id}` |
| `callbacks_resend` | `POST /user/callbacks/resend/{transactionId}` |
| `callbacks_resend_bulk` | `POST /user/callbacks/resend` |
### MED 违规(5) [#med-违规5]
| Tool | HTTP |
| ---------------------------- | ------------------------------------------------- |
| `infractions_list` | `GET /user/infractions` |
| `infractions_get` | `GET /user/infractions/{id}` |
| `infractions_create_defense` | `POST /user/infractions/{id}/defenses`(multipart) |
| `infractions_list_defenses` | `GET /user/infractions/{id}/defenses` |
| `infractions_get_defense` | `GET /user/infractions/{id}/defenses/{defenseId}` |
## 默认约定 [#默认约定]
* 金额以雷亚尔小数形式传入。tool 拒绝分单位:`9990` 会触发校验错误,必须是 `99.90`。
* 创建类调用必须传 `clientReference`(幂等)。
* 创建类调用必须传 `callbackUrl`,否则没人通知你状态。
* 5xx/429 自动重试,采用指数退避 + jitter(最多 3 次)。
* 错误信息包含 `requestId`,如需协助直接复制给支持团队。
* 零 admin endpoints,仅暴露公开与客户端层面。
### 环境变量 [#环境变量]
| Env var | 必填 | 默认值 | 说明 |
| --------------- | -- | ---------------------------------------- | --------------------------------------------------------------------- |
| `PAYZU_TOKEN` | 是 | | 来自 [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br) 的 token |
| `PAYZU_API_URL` | 否 | `https://api.payzu.processamento.com/v1` | whitelabel 场景下覆盖 |
## 支持 [#支持]