# MCP server (/docs/pix-processamento/mcp)
## O que é [#o-que-é]
`payzu-mcp-pix` é um servidor MCP local. Ele roda na sua máquina via `npx` e conversa por stdio com o assistente de IA. Também existe a [versão hospedada](#servidor-hospedado-sem-instalação), sem instalar nada. Nos dois casos o assistente decide qual tool chamar e o servidor executa a chamada HTTP na API Pix Processamento usando o seu token.
[MCP](https://modelcontextprotocol.io) é o protocolo aberto que deixa assistentes de IA chamarem ferramentas externas via JSON-RPC. Use o MCP quando quiser que o assistente execute ações reais na sua conta durante o desenvolvimento ou o uso interativo. Se o objetivo é o seu app em produção falar com a PayZu, use o [SDK](/docs/pix-processamento/sdks) (`payzu-pix`).
Requer `payzu-mcp-pix` 0.6.0 ou superior e Node 20 ou superior.
## Antes de começar [#antes-de-começar]
Pegue o token de API em [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br):
1. Entre na sua conta.
2. Abra a área de credenciais (a seção de token de API).
3. Copie o token. Esse valor vai em `PAYZU_TOKEN`.
O token dá acesso real à sua conta: criar cobrança, pagar Pix e ver saldo. Trate como senha. Recomendamos aprovar cada ação do agente antes de executar, em vez de deixar rodar sozinho.
## Servidor hospedado (sem instalação) [#servidor-hospedado-sem-instalação]
Não quer instalar nada? Aponte qualquer client MCP compatível para o servidor hospedado:
```
https://mcp.payzu.com.br/mcp
```
* **claude.ai e Claude Desktop**: Configurações → Conectores → *Adicionar conector personalizado* → cole a URL. Uma página da PayZu abre pedindo o token uma única vez (OAuth); o assistente nunca vê nem armazena o token.
* **Cursor / VS Code**: instalação em um clique:
[](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` (o fluxo de autorização abre no primeiro uso). Alternativa sem OAuth: envie o header `Authorization` com o Bearer token da API: `--header "Authorization: Bearer "`.
* **Claude Desktop (instalador local)**: baixe o [payzu-mcp-pix.mcpb](https://github.com/PayZuAI/payzu-mcp/releases/latest) e abra o arquivo; o Claude pede só o token.
O servidor hospedado é stateless: não armazena token nem dado de conta. Cada requisição é repassada à API Pix Processamento com a sua credencial, exatamente como uma chamada direta.
**Saque, estorno e transferência interna ficam desabilitados no servidor hospedado.** Eles exigem token com escopo `WITHDRAW`, e a conta que tem esse token só aceita chamadas de IP cadastrado; o hospedado sai por um IP compartilhado entre todos os clientes. As demais ferramentas só funcionam no hospedado se a conta não tiver IP cadastrado nem token ativo com escopo `WITHDRAW`: com IP cadastrado, toda a API aceita apenas esses IPs (`PZA203`); sem IP e com token `WITHDRAW` ativo, toda chamada é recusada, com qualquer token da conta (`PZA205`). Fora desse caso, use o **app local** (`npx payzu-mcp-pix` ou o instalador `.mcpb`) numa máquina com o IP público cadastrado no painel, menu **Segurança**, ou opere pelo painel. Veja a [whitelist de IP](/docs/pix-processamento/authentication#whitelist-de-ip).
## Google Antigravity [#google-antigravity]
Na interface do Antigravity:
1. No painel do agente (Agent Manager), clique no menu `...` no topo.
2. Escolha `MCP Servers` e depois `Manage MCP Servers`.
3. Clique em `View raw config`.
4. Cole a configuração abaixo, trocando pelo seu token:
```json
{
"mcpServers": {
"payzu-pix": {
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "seu-token-aqui" }
}
}
}
```
Cole o token literal dentro de `env`. A expansão de variáveis `${VAR}` falha em algumas versões.
O arquivo de config fica em:
* `~/.gemini/config/mcp_config.json` nas versões novas (Antigravity 2.0).
* `~/.gemini/antigravity/mcp_config.json` em builds anteriores.
Salve e clique em `Refresh` na tela `Manage MCP Servers`.
O Antigravity precisa de `payzu-mcp-pix` 0.6.0 ou superior. Os nomes de tools com ponto das versões antigas eram rejeitados pelos modelos (Gemini, Claude, GPT) que o Antigravity usa.
## Claude Code [#claude-code]
```bash
claude mcp add payzu-pix --env PAYZU_TOKEN=seu-token -- npx -y payzu-mcp-pix
```
Use `--scope user` para o servidor valer em todos os projetos:
```bash
claude mcp add payzu-pix --scope user --env PAYZU_TOKEN=seu-token -- npx -y payzu-mcp-pix
```
## Claude Desktop [#claude-desktop]
Edite `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"payzu-pix": {
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "seu-token-aqui" }
}
}
}
```
Reinicie o Claude Desktop depois de salvar.
## Cursor [#cursor]
Edite `.cursor/mcp.json` no projeto ou `~/.cursor/mcp.json` para valer em todos:
```json
{
"mcpServers": {
"payzu-pix": {
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "seu-token-aqui" }
}
}
}
```
## VS Code (GitHub Copilot) [#vs-code-github-copilot]
Edite `.vscode/mcp.json`. Aqui a chave é `servers` (não `mcpServers`), com `type` igual a `stdio`. Use `inputs` com `promptString` e `password` para o token não ser commitado:
```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": "Token de API PayZu",
"password": true
}
]
}
```
## Windsurf [#windsurf]
Edite `~/.codeium/windsurf/mcp_config.json`, mesmo formato `mcpServers`:
```json
{
"mcpServers": {
"payzu-pix": {
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "seu-token-aqui" }
}
}
}
```
## Passo a passo de uso [#passo-a-passo-de-uso]
1. Pegue o token em [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br).
2. Configure o seu cliente (Antigravity, Claude Code, Claude Desktop, Cursor, VS Code ou Windsurf) com um dos blocos acima.
3. Peça uma cobrança em linguagem natural, por exemplo:
> "Crie uma cobrança Pix de R$ 50,00 com referência pedido-001 e callback [https://meusite.com.br/webhook](https://meusite.com.br/webhook)"
4. O agente chama `pix_create` e devolve o `id` e o `qrCodeText` da cobrança.
5. Pergunte "qual meu saldo?" e o agente chama `account_balance` e responde com o número.
### Não funcionou? [#não-funcionou]
* Erro `[401]`: token inválido ou expirado. Gere um novo em [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br).
* Servidor não aparece na lista de tools: recarregue ou reinicie o cliente (no Antigravity, use `Refresh`).
## Lista de tools (48) [#lista-de-tools-48]
Todos os nomes em snake\_case. Cada tool tem `description` com link direto para a página do endpoint na doc.
### Cobranças Pix (4) [#cobranças-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}` |
### Pagamentos Pix (6) [#pagamentos-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}` |
### Estorno (1) [#estorno-1]
| Tool | HTTP |
| ----------------- | ------------------------------ |
| `refund_create` ¹ | `POST /refund/{transactionId}` |
### Webhooks (8) [#webhooks-8]
| Tool | HTTP |
| ------------------------ | ------------------------------------------- |
| `webhooks_create` | `POST /user/webhooks` |
| `webhooks_list` | `GET /user/webhooks` |
| `webhooks_get` | `GET /user/webhooks/{id}` |
| `webhooks_update` | `PATCH /user/webhooks/{id}` |
| `webhooks_delete` | `DELETE /user/webhooks/{id}` |
| `webhooks_rotate_secret` | `POST /user/webhooks/{id}/rotate-secret` |
| `webhooks_sent_quantity` | `GET /user/webhooks/sent/quantity` |
| `webhooks_sent_detail` | `GET /user/webhooks/{id}/sent/{callbackId}` |
### Transferência interna (2) [#transferência-interna-2]
| Tool | HTTP |
| ---------------------------- | ------------------------- |
| `internal_transfer_create` ¹ | `POST /internal-transfer` |
| `internal_transfer_get` | `GET /internal-transfer` |
### Conta (3) [#conta-3]
| Tool | HTTP |
| ------------------ | ---------------------------- |
| `account_profile` | `GET /user` |
| `account_balance` | `GET /user/balance` |
| `account_pix_keys` | `GET /user/dict?key={chave}` |
### Relatórios (11) [#relatórios-11]
| 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` |
| `reports_bank_statements` | `GET /user/bank-statements` |
| `reports_bank_statement` | `GET /user/bank-statements/{id}` |
| `reports_deposit_pending` | `GET /user/deposit-pending` |
| `reports_deposit_pending_get` | `GET /user/deposit-pending/{id}` |
| `reports_summary` | `GET /user/summary` |
### Callbacks (8) [#callbacks-8]
| 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` |
| `callbacks_resend_webhook` | `POST /user/callbacks/resend/webhook/{webhookId}` |
| `callbacks_resend_webhook_bulk` | `POST /user/callbacks/resend/webhook` |
| `callbacks_create_secret` | `POST /user/callbacks/secret` |
| `callbacks_rotate_secret` | `PATCH /user/callbacks/secret/rotate` |
### Infrações MED (5) [#infrações-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}` |
¹ Desabilitadas no servidor hospedado, pelo motivo do aviso acima: elas entram como stub e respondem que a operação não está disponível. Funcionam no app local (`npx payzu-mcp-pix` ou o instalador `.mcpb`).
## Convenções aplicadas [#convenções-aplicadas]
* Valores em **reais decimais**, nunca em centavos: R$ 99,90 é `99.90`.
* `clientReference` obrigatório nas criações (idempotência).
* `callbackUrl` é opcional nas criações. Sem ele não há entrega para aquela transação; os webhooks cadastrados continuam recebendo os eventos, e o status também sai pela tool de consulta.
* Auto-retry só em requisição de leitura (`GET`, `HEAD`, `OPTIONS`) e só nos status 408, 429, 500, 502, 503 e 504, com backoff exponencial e jitter, até 3 retentativas. **Criação nunca é retentada**: um `POST` que falhou não vira cobrança duplicada.
* Erros incluem `requestId`, copie e cole no suporte se precisar.
* Zero endpoints admin, só a superfície pública e do cliente.
**O valor não é validado contra engano de unidade.** O schema aceita qualquer número positivo com até 2 casas, então `9990` passa e vira uma cobrança de **R$ 9.990,00**, não de R$ 99,90. Se o seu código guarda valor em centavos, divida por 100 antes de pedir para o agente.
### Variáveis de ambiente [#variáveis-de-ambiente]
| Env var | Obrigatório | Default | Descrição |
| --------------- | ----------- | ---------------------------------------- | ------------------------------------------------------------------- |
| `PAYZU_TOKEN` | sim | | Token de [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br) |
| `PAYZU_API_URL` | não | `https://api.payzu.processamento.com/v1` | Override para whitelabel |
## Suporte [#suporte]