Comece aquiFerramentas

Servidor MCP


Nesta páginaComo funcionaEscolha o modoConecte o clienteFerramentasRegras das ferramentasRevogue o acessoPróximos passos

Conecte 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.

Fluxo do servidor MCP: o cliente MCP escolhe a ferramenta, o servidor MCP traduz a chamada e repassa o seu token, e a API do PayZu Pix responde

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

ModoEndereço ou comandoOnde fica o tokenO que funciona
Hospedadohttps://mcp.payzu.com.br/mcpA 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 tokenAs 47 existem, mas quatro não operam
Localnpx -y @payzu/mcp-pixNa variável de ambiente PAYZU_TOKEN da sua máquinaAs 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.

GrupoFerramentasRotas
Cobrançaspix_create, pix_get, pix_qr_code, pix_proofPOST /pix, GET /pix, GET /pix/qr-code/{transactionId}, GET /proof/{id}
Saqueswithdraw_create, withdraw_get, withdraw_by_qr, withdraw_read_qr, withdraw_proofPOST /withdraw, GET /withdraw, POST /withdraw/qrcode, POST /pix/qrcode/read, GET /withdraw/proof/{id}
Consulta DICTwithdraw_dictGET /pix/key: consulta o titular de uma chave de terceiro
Devoluçãorefund_createPOST /refund/{transactionId}
Transferência internainternal_transfer_create, internal_transfer_getPOST /internal-transfer, GET /internal-transfer

Regras das ferramentas

RegraEfeito
Valor em reais, com casas decimais10.9 é R$ 10,90. O esquema não detecta valor em centavos: 1090 passa e vale R$ 1.090,00
clientReferenceObrigató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
callbackUrlOpcional nas criações. Sem ele, acompanhe pelas ferramentas de consulta
Repetição automáticaSó 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
ErrosTrazem 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.

ModoEfeito da troca
HospedadoTodos 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
LocalO pacote usa o token direto e para de funcionar

Próximos passos