AdvinPay MCP

Servidor MCP (Model Context Protocol) oficial da AdvinPay. Conecte o Claude, Cursor ou qualquer cliente MCP à sua conta AdvinPay para criar cobranças PIX, consultar transações e tirar dúvidas da documentação direto do assistente.

• 📚 Documentação da API embutida e pesquisável (funciona sem credenciais)
• 💸 Criar QR Code PIX e consultar transações com suas chaves de API
• 🔒 Saques desabilitados por padrão — opt-in explícito
• 📦 Zero configuração: roda com npx advinpay-mcp

Configuração

Gere suas credenciais no dashboard (Dashboard → API) e configure no seu cliente MCP:

Claude Code

claude mcp add advinpay \
  -e ADVINPAY_ACCESS_KEY=ak_sua_chave \
  -e ADVINPAY_SECRET_KEY=sk_seu_secret \
  -- npx -y advinpay-mcp

Claude Desktop / Cursor (JSON)

{
  "mcpServers": {
    "advinpay": {
      "command": "npx",
      "args": ["-y", "advinpay-mcp"],
      "env": {
        "ADVINPAY_ACCESS_KEY": "ak_sua_chave",
        "ADVINPAY_SECRET_KEY": "sk_seu_secret"
      }
    }
  }
}

Sem credenciais, o servidor ainda funciona — apenas as ferramentas de documentação e de consulta pública ficam disponíveis.

Ferramentas

Ferramenta	Credenciais	Descrição
search_docs	não	Busca na documentação oficial da API
read_docs	não	Lê uma seção da documentação (ou o guia completo)
get_public_charge	não	Consulta pública de uma cobrança (checkout)
create_pix_deposit	API Key	Cria cobrança PIX e retorna o copia-e-cola
get_transaction	API Key	Consulta status/detalhes de uma transação
create_pix_withdrawal	API Key	⚠️ Saque PIX real — desabilitada por padrão

O servidor também expõe a documentação completa como resource MCP (advinpay://docs/llms.txt).

Habilitando saques (opcional)

create_pix_withdrawal movimenta dinheiro de verdade e por isso só é registrada quando você define explicitamente:

ADVINPAY_MCP_ALLOW_WITHDRAWALS=true

Recomendações antes de habilitar:

• Use credenciais com escopo mínimo (transactions:withdrawal só se necessário).
• Prefira uma conta com limites configurados.
• Confirme sempre valor e chave PIX antes de aprovar a chamada no seu cliente MCP.

Variáveis de ambiente

Variável	Obrigatória	Descrição
ADVINPAY_ACCESS_KEY	para tools de API	Access Key (ak_...)
ADVINPAY_SECRET_KEY	para tools de API	Secret Key (sk_...)
ADVINPAY_MCP_ALLOW_WITHDRAWALS	não	true habilita a tool de saque
SITE_URL / baseUrl	não	Padrão: https://api.advinpay.com/v1

Exemplos de uso (no chat)

• “Crie uma cobrança PIX de R$ 250 para o cliente João Silva, CPF 123.456.789-09, referente ao pedido 442.”
• “Qual o status da transação a1b2c3d4-…?”
• “Como funciona o retry dos webhooks da AdvinPay?”
• “Me mostre como autenticar na API e quais escopos existem.”

Desenvolvimento

pnpm install   # usa o SDK local via override (../advinpay-sdk) enquanto `advinpay` não está no npm
pnpm test
pnpm build
node dist/index.js   # roda o servidor em stdio

O pnpm-workspace.yaml contém um override advinpay: link:../advinpay-sdk para desenvolvimento. Depois que o pacote advinpay for publicado no npm, o override pode ser removido.

Licença

MIT © AdvinPay