Sua API, operada por IA: apresentando o MCP Server oficial da PushinPay

npx -y @pushinpaybr/mcp-server

Uma linha no terminal. É o que separa o seu agente de IA da API da PushinPay.

Publicamos no npm o @pushinpaybr/mcp-server, nosso servidor MCP oficial. Na prática, isso significa que Claude Desktop, Claude Code, Cursor — ou qualquer cliente compatível com o protocolo — passa a criar cobranças PIX, consultar saldo e verificar transações em linguagem natural, sem que você escreva uma linha de código de integração.

Este post explica o que o pacote faz, o que ele deliberadamente não faz, e como colocar pra rodar em dois minutos.

O que é MCP, em 30 segundos

O Model Context Protocol (MCP) é um protocolo aberto que padroniza a forma como agentes de IA se conectam a sistemas externos — APIs, bancos de dados, ferramentas. A analogia clássica é o USB-C: em vez de cada integração exigir um conector proprietário, o protocolo define uma interface única. O cliente de IA descobre quais ferramentas ("tools") o servidor expõe, o que cada uma faz e quais parâmetros aceita — e o agente decide sozinho quando e como usá-las a partir do que você pede em linguagem natural.

Se você já perdeu uma tarde escrevendo wrapper de API, tratando autenticação e montando requisição só pra fazer um protótipo funcionar, é exatamente essa tarde que o MCP elimina.

As três tools do pacote

A v1 expõe três operações:

criar_cobranca_pix — cria uma cobrança PIX e devolve o copia-e-cola e o QR Code. Aceita split opcional, então dá pra dividir o valor entre contas no momento da criação — o caso de uso clássico de co-produção e afiliados.

consultar_transacao — retorna o status de uma transação pelo ID. Vem com uma trava de 1 consulta por minuto embutida no próprio servidor, e aqui vale explicar o porquê: agente de IA adora entrar em loop de polling, e polling agressivo de status direto na API pode levar ao bloqueio da conta. No MCP, a trava já vem aplicada — o agente ansioso perguntando "já pagou?" quatro vezes por segundo esbarra no servidor, não na sua conta.

consultar_saldo — saldo disponível e valor bloqueado da conta, em tempo real.

O que ficou de fora — de propósito

Tão importante quanto o que o pacote faz é o que ele não faz: a v1 não expõe saque, reembolso nem alteração de conta.

Isso é decisão de arquitetura, não limitação técnica. Dar a um agente autônomo acesso a uma API financeira exige escopo mínimo: no pior cenário — um agente que alucina, um prompt mal escrito, um loop inesperado — o dano possível é uma cobrança criada a mais. Nunca dinheiro saindo da conta, nunca configuração alterada.

Conforme o padrão de uso amadurecer, o escopo evolui. Mas a régua de segurança vem primeiro.

Instalação

Claude Desktop e Cursor

Adicione ao arquivo de configuração MCP do cliente:

{
  "mcpServers": {
    "pushinpay": {
      "command": "npx",
      "args": ["-y", "@pushinpaybr/mcp-server"],
      "env": {
        "PUSHINPAY_TOKEN": "seu_token_aqui",
        "PUSHINPAY_ENV": "sandbox"
      }
    }
  }
}

Só isso. O npx -y baixa e executa o pacote — não precisa clonar repositório nem instalar nada globalmente. O token você gera no painel da PushinPay.

Claude Code

No terminal:

claude mcp add pushinpay \
  -e PUSHINPAY_TOKEN=seu_token_aqui \
  -e PUSHINPAY_ENV=sandbox \
  -- npx -y @pushinpaybr/mcp-server

O Claude Code trabalha com três escopos de configuração, e vale escolher com intenção:

  • local (padrão) — o servidor fica disponível só no projeto atual, privado pra você. Ideal pra testar.
  • project (--scope project) — grava num arquivo .mcp.json na raiz do repositório, versionado no git. Todo o time que clonar o projeto herda a configuração. Atenção: esse arquivo vai pro repositório — nunca coloque o token literal nele; referencie variável de ambiente.
  • user (--scope user) — disponível em todos os seus projetos, na sua máquina. É o "escopo global".

Na prática

Com o servidor configurado, isso passa a funcionar:

"Cria uma cobrança PIX de R$ 149,90 e me devolve o copia-e-cola."
"Qual o status da transação 9d2f...?"
"Quanto tenho de saldo disponível agora?"

O agente identifica a tool certa, monta os parâmetros, executa a chamada e devolve o resultado estruturado. Pra prototipagem, automação interna, dashboards conversacionais ou simplesmente operar a conta sem abrir o painel, a diferença de fricção é grande.

Documentação que o agente lê sozinho

Aqui está o detalhe de que a gente mais gosta: o pacote se autodocumenta.

O próprio repositório no npm aponta para três artefatos:

  • llms.txt — a documentação da API em formato pensado pra consumo por modelos de linguagem, incluindo as regras críticas de uso
  • OpenAPI spec — o contrato da API em OpenAPI 3.0, machine-readable
  • SKILL.md — instruções de uso estruturadas pro agente, no padrão de Skills

Na prática: quando o seu agente instala ou inspeciona o MCP, ele encontra o caminho pra documentação completa e descobre sozinho como usar a API — endpoints, parâmetros, formatos, limites. Você também pode apontar manualmente, claro. Documentação escrita pra máquina ler e pra humano auditar.

O servidor também está listado no MCP Registry, o diretório oficial de servidores do protocolo.

Antes de ir pra produção

Quatro boas práticas que valem o parágrafo:

  1. Comece no sandbox. PUSHINPAY_ENV tem sandbox como valor padrão — valide o fluxo inteiro lá antes de trocar pra production. O ambiente sandbox é liberado mediante solicitação ao suporte, então peça a ativação antes de começar. Agente de IA criando cobrança real no primeiro teste é o tipo de surpresa que ninguém quer.
  2. Token sempre via variável de ambiente. Nunca commitado no repositório, nunca colado num .mcp.json versionado. Se expor, revogue e gere outro no painel.
  3. Liberou o IP do token? Tokens podem ser vinculados a uma lista de IPs autorizados. Um agente rodando na sua máquina — IP residencial, dinâmico — pode tomar 401 "IP não configurado". Nesse caso, ajuste a liberação de IP do token no painel.
  4. Respeite a trava de consulta. A limitação de 1 consulta/min no consultar_transacao existe pra proteger a sua conta. Se o seu caso de uso exige confirmação de pagamento em tempo real, o caminho certo é o webhook_url da cobrança — não polling via agente.

Escopo v1, feedback aberto

O pacote está em v1, em construção declarada. O escopo atual — leitura + criação de cobrança — é o começo, não o teto, e a ordem de evolução vai ser ditada pelo uso real. Se você integrou, testou, quebrou algo ou sentiu falta de alguma tool, a gente quer saber.

O canal direto com o time técnico é o fórum de desenvolvedores no nosso Discord. Issue bem descrita lá tem prioridade de verdade.

Links

  • npm: https://www.npmjs.com/package/@pushinpaybr/mcp-server
  • llms.txt: https://pushinpay.com.br/llms.txt
  • OpenAPI spec: https://pushinpay.com.br/openapi.yaml
  • SKILL.md: https://pushinpay.com.br/skill/SKILL.md
  • MCP Registry: https://registry.modelcontextprotocol.io/?q=pushinpay
  • Documentação da API: https://docs.pushinpay.com.br/
  • Discord (fórum dev): https://discord.gg/7hqVpEKYWt