MCP server

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, 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 é 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 (payzu-pix).

Antes de começar

Pegue o token de API em 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.

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:

• 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 <seu-token>".
• Claude Desktop (instalador local): baixe o payzu-mcp-pix.mcpb 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.

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:

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

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.

Claude Code

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:

claude mcp add payzu-pix --scope user --env PAYZU_TOKEN=seu-token -- npx -y payzu-mcp-pix

Claude Desktop

Edite ~/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-aqui" }
    }
  }
}

Reinicie o Claude Desktop depois de salvar.

Cursor

Edite .cursor/mcp.json no projeto ou ~/.cursor/mcp.json para valer em todos:

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

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:

{
  "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

Edite ~/.codeium/windsurf/mcp_config.json, mesmo formato mcpServers:

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

Passo a passo de uso

1. Pegue o token em 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"

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?

• Erro [401]: token inválido ou expirado. Gere um novo em 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)

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)

Pagamentos Pix (6)

Estorno (1)

Webhooks (8)

Transferência interna (2)

Conta (3)

Relatórios (11)

Callbacks (8)

Infrações MED (5)

¹ 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

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

Variáveis de ambiente

Suporte