Ir para o conteúdo
Docs

MCP para agentes de IA

Conecte Claude, Cursor, ChatGPT e outros agentes à sua conta pelo Model Context Protocol, com uma chave de API dedicada.

O que é

O Model Context Protocol (MCP) é o padrão aberto que agentes de IA usam para chamar ferramentas externas. Com o servidor MCP da MaxxiPay, um agente como Claude, Cursor ou ChatGPT consulta saldo, cobranças, saques e eventos da sua conta, e pode criar cobranças e saques PIX quando a chave permitir.

Cada tool chama a mesma regra da API REST: os mesmos escopos, a mesma verificação da conta, o mesmo limite de 300 requisições por minuto por chave e o mesmo formato de resposta da referência. Valores sempre em centavos.

URL e autenticação

O servidor fica em https://api.maxxipay.com/mcp e usa o transporte Streamable HTTP: cada mensagem JSON-RPC é um POST e a resposta vem em JSON. Não há sessão para manter. GET e DELETE respondem 405.

A autenticação é só por chave de API no cabeçalho Authorization: Bearer. Sessões do painel não são aceitas. Crie uma chave só para o agente com os escopos mínimos:

EscopoPermite
balance:readConsultar o saldo disponível, a liquidar e bloqueado.
charges:readConsultar e listar cobranças e seus eventos.
payouts:readConsultar e listar saques e seus eventos.

Acrescente charges:write ou payouts:write só se o agente precisar criar cobranças ou saques.

CabeçalhosHTTP
POST /mcp HTTP/1.1
Host: api.maxxipay.com
Authorization: Bearer mxp_live_SUA_CHAVE
Content-Type: application/json
Accept: application/json, text/event-stream

Configurar o cliente

Troque mxp_live_SUA_CHAVE pela chave criada para o agente e reinicie o cliente.

  • Claude Desktop: edite claude_desktop_config.json. A ponte mcp-remote roda via npx e repassa o cabeçalho de autenticação.
  • Claude Code: rode claude mcp add com --transport http e o cabeçalho.
  • Cursor: crie .cursor/mcp.json no projeto, ou use o arquivo global em ~/.cursor/mcp.json.
  • Outros clientes com transporte HTTP: informe a URL e o cabeçalho Authorization. O exemplo em curl abre a conexão com initialize.
Configuração
{
  "mcpServers": {
    "maxxipay": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.maxxipay.com/mcp", "--header", "Authorization:${MAXXIPAY_AUTH}"],
      "env": {
        "MAXXIPAY_AUTH": "Bearer mxp_live_SUA_CHAVE"
      }
    }
  }
}

Tools disponíveis

tools/list mostra só as tools que os escopos da chave permitem. A resposta de cada tool traz o objeto em structuredContent e o mesmo JSON em texto.

ToolEscopoO que faz
get_balancebalance:readSaldo disponível, a liquidar e bloqueado, em centavos.
list_chargescharges:readCobranças mais recentes, com filtro por status e externalId.
get_chargecharges:readUma cobrança pelo identificador, com o PIX copia e cola e a imagem do QR Code.
create_chargecharges:writeGera uma cobrança PIX com o copia e cola e a imagem do QR Code. Exige idempotencyKey e a conta verificada.
list_payoutspayouts:readSaques mais recentes, com filtro por status e externalId.
get_payoutpayouts:readUm saque pelo identificador.
create_payoutpayouts:writeEnvia dinheiro do saldo para uma chave PIX. Exige payouts:write, idempotencyKey e a conta verificada.
list_eventscharges:read ou payouts:readEventos de webhook com a situação de entrega.

Erros de negócio voltam como resultado com isError: true e o texto código: mensagem, com os mesmos códigos da API. Argumentos inválidos voltam do mesmo jeito, com o campo a corrigir.

Chamada de toolJSON
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_charge",
    "arguments": {
      "amountCents": 4990,
      "description": "Pedido 1042",
      "payerName": "Maria Souza",
      "payerDocument": "52998224725",
      "externalId": "pedido-1042",
      "idempotencyKey": "pedido-1042-cobranca"
    }
  }
}

Segurança

  • Use uma chave dedicada por agente. Assim você revoga o acesso dele sem parar as outras integrações.
  • Comece só com leitura: balance:read, charges:read e payouts:read. Mantenha payouts:write fora de agentes que não precisam enviar dinheiro.
  • create_charge e create_payout exigem a conta verificada. Antes disso, respondem account_not_verified.
  • As tools de criação exigem idempotencyKey, de 8 a 120 caracteres. Repetir a mesma chave devolve o mesmo recurso, sem duplicar a cobrança ou o saque.
  • Peça ao agente para confirmar valor e destino com você antes de criar um saque.
  • Se a chave vazar ou o agente não for mais usado, revogue a chave no painel. O acesso para na hora.

Versões do protocolo

VersãoComo conectar
2026-07-28Atual. Sem initialize: cada POST traz MCP-Protocol-Version e o mesmo valor em _meta. Use server/discover para conhecer o servidor.
2025-11-25Com initialize. A versão é negociada no handshake.
2025-06-18Com initialize. A versão é negociada no handshake.
2025-03-26Com initialize. A versão é negociada no handshake.

Se o cliente pedir no initialize uma versão fora da lista, o servidor responde com 2025-11-25. Na versão atual, cabeçalhos que não batem com o corpo recebem 400 com o código -32020, e versões não suportadas recebem 400 com -32022 e a lista de versões aceitas.

esc