MCP server

npm payzu-mcp-pix Repo no GitHub SKILL.md (alternativa leve)

MCP é o protocolo aberto que deixa assistentes de IA chamarem ferramentas externas via JSON-RPC. O payzu-mcp-pix expõe 29 tools curadas da API Pix Processamento, com nomes legíveis (pix.create, account.balance, etc), validação de tipos e tratamento de erro consistente.

Quando usar MCP vs SKILL.md vs SDK

Cenário	Use
IA executa chamadas reais na sua conta PayZu (criar Pix, ver saldo, etc)	MCP
IA gera código que você cola no seu app	SKILL.md
Seu app em produção fala com a PayZu	SDK (`npm install payzu-pix`)

Instalação

Claude Desktop

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

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": {
        "PAYZU_TOKEN": "<seu-token-do-dashboard>"
      }
    }
  }
}

Reinicia o Claude Desktop. Testa pedindo "qual meu saldo PayZu?", o Claude vai chamar account.balance sozinho.

Cursor

.cursor/mcp.json no projeto (ou ~/.cursor/mcp.json global):

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

Continue, Codeium, outros

Mesma config (todos seguem o padrão MCP). Veja o README do pacote para detalhes.

Configuração

Env var	Obrigatório	Default	Descrição
`PAYZU_TOKEN`	sim	,	Bearer token de abrirconta.payzu.com.br
`PAYZU_API_URL`	não	`https://api.payzu.processamento.com/v1`	Override pra whitelabel

Lista de tools (29)

Todos os nomes em snake_case com namespace por domínio. Cada tool tem description com link direto pra página do endpoint na doc.

Cobranças Pix (4)

Tool	HTTP
`pix.create`	`POST /pix`
`pix.get`	`GET /pix`
`pix.qr_code`	`GET /pix/qr-code/{id}`
`pix.proof`	`GET /proof/{id}`

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/{key}`
`withdraw.proof`	`GET /withdraw/proof/{id}`

Transferência interna (2)

Tool	HTTP
`internal_transfer.create`	`POST /internal-transfer`
`internal_transfer.get`	`GET /internal-transfer`

Conta (2)

Tool	HTTP
`account.profile`	`GET /user`
`account.balance`	`GET /user/balance`

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/reports`
`reports.get_job`	`GET /user/report/{id}`
`reports.download`	`GET /user/report/{id}/download`

Callbacks (4)

Tool	HTTP
`callbacks.list`	`GET /user/callbacks`
`callbacks.get`	`GET /user/callback/{id}`
`callbacks.resend`	`POST /user/callback/{id}/resend`
`callbacks.resend_bulk`	`POST /user/callbacks/resend`

Infrações MED (5)

Tool	HTTP
`infractions.list`	`GET /infractions`
`infractions.get`	`GET /infractions/{id}`
`infractions.create_defense`	`POST /infractions/{id}/defense`
`infractions.list_defenses`	`GET /infractions/{id}/defenses`
`infractions.get_defense`	`GET /infractions/{id}/defense/{defenseId}`

Convenções aplicadas

Valores em REAIS decimais, tool rejeita centavos (9990 vira erro de validação; tem que ser 99.90).
clientReference obrigatório em criações (idempotência).
callbackUrl obrigatório em criações (sem isso ninguém te avisa o status).
Auto-retry em 5xx/429 com backoff exponencial + jitter (max 3 tentativas).
Erros incluem requestId, copia e cola no suporte se precisar.
Zero endpoints admin, só superfície pública/cliente.

Exemplo de uso (Claude Desktop)

Depois de configurar, conversas tipo:

"Cria uma cobrança PayZu de R$ 50 com referência order-abc"

Claude vai escolher pix.create, validar os argumentos e chamar a API. Te mostra o id, qrCodeText e qrCodeUrl no chat.

"Quanto eu tenho de saldo?"

Claude chama account.balance e responde com o número.

"Lista as últimas 10 transações canceladas"

Claude chama reports.list_transactions com status: CANCELED, limit: 10.

Suporte

Reportar bug Doc completa Suporte PayZu

MCP server

On this page