Servidor MCP
Nesta página
Como funcionaEscolha o modoConecte o clienteFerramentasRegras das ferramentasRevogue o acessoPróximos passosConecte um assistente ou agente de IA ao PayZu Pix, o único produto da PayZu com servidor MCP (Model Context Protocol), para que ele chame a API como ferramentas tipadas, com o seu token.
Como funciona
A sua aplicação, ou o cliente MCP que você usa, escolhe a ferramenta e os argumentos. O servidor traduz para a chamada HTTP, repassa o seu token e retorna o resultado. Ele não guarda credencial nem estado.
Escolha o modo
| Modo | Endereço ou comando | Onde fica o token | O que funciona |
|---|---|---|---|
| Hospedado | https://mcp.payzu.com.br/mcp | A página de autorização da PayZu pede o token da API uma vez, por OAuth, e entrega ao cliente um token selado, aberto a cada chamada. O cliente nunca vê o token | As 47 existem, mas quatro não operam |
| Local | npx -y @payzu/mcp-pix | Na variável de ambiente PAYZU_TOKEN da sua máquina | As 47, saindo do IP da sua máquina |
Quatro ferramentas não operam no modo hospedado.
Elas existem nele, mas withdraw_create, withdraw_by_qr, refund_create e internal_transfer_create respondem que a operação não está disponível.
Conta com IP cadastrado ou que envia Pix pela API precisa do pacote local.
Nela, o servidor hospedado é recusado em qualquer ferramenta, inclusive account_balance, com 403 e PZA203 ou PZA205.
Conecte o cliente
Ferramentas
As 47 ferramentas cobrem as rotas públicas da API, sem rotas administrativas.
| Grupo | Ferramentas | Rotas |
|---|---|---|
| Cobranças | pix_create, pix_get, pix_qr_code, pix_proof | POST /pix, GET /pix, GET /pix/qr-code/{transactionId}, GET /proof/{id} |
| Saques | withdraw_create, withdraw_get, withdraw_by_qr, withdraw_read_qr, withdraw_proof | POST /withdraw, GET /withdraw, POST /withdraw/qrcode, POST /pix/qrcode/read, GET /withdraw/proof/{id} |
| Consulta DICT | withdraw_dict | GET /pix/key: consulta o titular de uma chave de terceiro |
| Devolução | refund_create | POST /refund/{transactionId} |
| Transferência interna | internal_transfer_create, internal_transfer_get | POST /internal-transfer, GET /internal-transfer |
| Grupo | Ferramentas | Rotas |
|---|---|---|
| Conta | account_profile, account_balance | GET /user, GET /user/balance |
| Relatórios | reports_list_transactions, reports_get_transaction, reports_create_csv, reports_list_jobs, reports_get_job, reports_download, reports_bank_statements, reports_bank_statement, reports_deposit_pending, reports_deposit_pending_get, reports_summary | /user/transactions, /user/report, /user/bank-statements, /user/deposit-pending, /user/summary |
| Grupo | Ferramentas | Rotas |
|---|---|---|
| Webhooks | webhooks_create, webhooks_list, webhooks_get, webhooks_update, webhooks_delete, webhooks_rotate_secret, webhooks_sent_quantity, webhooks_sent_detail | /user/webhooks e subrotas |
| Callbacks | callbacks_list, callbacks_get, callbacks_resend, callbacks_resend_bulk, callbacks_resend_webhook, callbacks_resend_webhook_bulk, callbacks_create_secret, callbacks_rotate_secret | /user/callbacks e subrotas |
| Grupo | Ferramentas | Rotas |
|---|---|---|
| MED | infractions_list, infractions_get, infractions_create_defense, infractions_list_defenses, infractions_get_defense | /user/infractions e subrotas |
Regras das ferramentas
| Regra | Efeito |
|---|---|
| Valor em reais, com casas decimais | 10.9 é R$ 10,90. O esquema não detecta valor em centavos: 1090 passa e vale R$ 1.090,00 |
clientReference | Obrigatório na cobrança, no saque, no pagamento de QR Code e na transferência; opcional na devolução. Repetir a referência aciona a deduplicação da API |
callbackUrl | Opcional nas criações. Sem ele, acompanhe pelas ferramentas de consulta |
| Repetição automática | Só nas ferramentas de leitura (GET), até 3 vezes, nos status 408, 429, 500, 502, 503 e 504, com espera crescente. Criações nunca são repetidas |
| Erros | Trazem o errorCode e o requestId da API, para registrar e enviar ao suporte |
Revogue o acesso
Para cortar um cliente conectado, troque o token da API pelo painel da sua conta.
| Modo | Efeito da troca |
|---|---|
| Hospedado | Todos os tokens emitidos a partir do token antigo deixam de funcionar na próxima chamada. Os tokens OAuth não têm estado, então não há sessão para apagar |
| Local | O pacote usa o token direto e para de funcionar |