# 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. Não é servidor hospedado e não tem URL: 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.3.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, sacar e ver saldo. Trate como senha. Recomendamos aprovar cada ação do agente antes de executar, em vez de deixar rodar sozinho.
## 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.3.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 (29) [#lista-de-tools-29]
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}` |
### Saques (6) [#saques-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}` |
### Transferência interna (2) [#transferência-interna-2]
| Tool | HTTP |
| -------------------------- | ------------------------- |
| `internal_transfer_create` | `POST /internal-transfer` |
| `internal_transfer_get` | `GET /internal-transfer` |
### Conta (2) [#conta-2]
| Tool | HTTP |
| ----------------- | ------------------- |
| `account_profile` | `GET /user` |
| `account_balance` | `GET /user/balance` |
### Relatórios (6) [#relatórios-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) [#callbacks-4]
| 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` |
### 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}` |
## Convenções aplicadas [#convenções-aplicadas]
* Valores em reais decimais. A tool rejeita centavos: `9990` vira erro de validação, tem que ser `99.90`.
* `clientReference` obrigatório nas criações (idempotência).
* `callbackUrl` obrigatório nas criações, senão ninguém te avisa o status.
* Auto-retry em 5xx/429 com backoff exponencial e jitter (máximo 3 tentativas).
* Erros incluem `requestId`, copie e cole no suporte se precisar.
* Zero endpoints admin, só a superfície pública e do cliente.
### 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]