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

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 (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)

Saques (6)

Transferência interna (2)

Conta (2)

Relatórios (6)

Callbacks (4)

Infrações MED (5)

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

Suporte