Abacate Pay MCP Server

Servidor MCP para usar a API v2 da Abacate Pay no Claude, no Cursor ou por URL remota (Claude.ai, automações, outras integrações).

Conteúdo: Início rápido · Como rodar o servidor · Conectar via OAuth (Claude.ai / remoto) · Ferramentas · Problemas comuns

Início rápido

Pré-requisito: Bun 1.x.

git clone https://github.com/AbacatePay/abacatepay-mcp.git
cd abacatepay-mcp
bun install

Chave de API: Abacate Pay → Integrar → API Keys. Use uma chave de API v2 — é a única versão suportada por este servidor.

Claude Desktop / Cursor (modo local, processo próprio):

{
  "mcpServers": {
    "abacate-pay": {
      "command": "bun",
      "args": ["/CAMINHO/absoluto/para/abacatepay-mcp/src/index.ts"],
      "env": {
        "ABACATE_PAY_API_KEY": "sua_chave"
      }
    }
  }
}

Muitas ferramentas também aceitam apiKey na própria chamada, para usar outra chave quando precisar (útil para operar em modo teste e produção sem trocar a configuração).

Related MCP server: Bayarcash MCP Server

Como rodar o servidor

Escolha uma opção.

No seu computador com Cursor ou Claude Desktop (o mais simples)

O próprio app liga o servidor para você via stdio (bun run src/index.ts). Você só configura o caminho e a variável ABACATE_PAY_API_KEY, como no início rápido. Não precisa de URL, porta ou OAuth.

Na internet (HTTP) — Claude.ai, n8n, automações

Use o endpoint público quando você integra com Claude.ai (conector remoto), n8n, outras automações, ou quer configuração remota no cliente (sem command/processo local).

Esse endpoint aceita dois modos de autenticação:

1. Authorization: Bearer <chave-v2> (ou header X-API-Key) diretamente — simples para clientes que já guardam a chave (n8n, scripts, Cursor apontando para a URL).

2. OAuth 2.0 — obrigatório para o conector remoto do Claude.ai, que não aceita headers estáticos e exige um fluxo de autorização. Veja a seção abaixo.

Exemplo de configuração remota (Cursor, com header direto):

{
  "mcpServers": {
    "abacatepay": {
      "url": "https://mcp.abacatepay.com/mcp",
      "headers": {
        "Authorization": "Bearer API_KEY"
      }
    }
  }
}

Local, servindo HTTP (para testar OAuth ou o modo multi-tenant)

bun run src/http-server.ts
# porta padrão 3000; ajuste com MCP_PORT ou PORT

Conectar via OAuth (Claude.ai / remoto)

O servidor implementa um Authorization Server OAuth 2.0 completo (Dynamic Client Registration + Authorization Code + PKCE), necessário porque o conector remoto do Claude.ai exige OAuth — não é possível conectar apenas com um header estático nesse cliente.

Fluxo, do ponto de vista do Claude/cliente MCP:

1. O cliente descobre os metadados em /.well-known/oauth-protected-resource e /.well-known/oauth-authorization-server.

2. Registra-se dinamicamente em POST /register (RFC 7591).

3. Abre GET /authorize no navegador do usuário — uma página simples pede a chave de API v2 da Abacate Pay (não uma senha de conta).

4. Após validar a chave contra a API (GET /v2/stores/get), o servidor emite um código de autorização e redireciona de volta ao cliente.

5. O cliente troca o código por um token em POST /token (com verificação PKCE). O "token" retornado é, na prática, a própria chave de API v2, guardada de forma criptografada (AES-256-GCM) no SQLite do servidor até esse ponto.

6. O cliente usa esse token como Authorization: Bearer normalmente em /mcp.

Não há conta de usuário nem senha do Abacate Pay envolvida — apenas a chave de API do lojista, o mesmo modelo de autenticação usado no header direto.

Configuração de produção (Fly.io): o banco de dados OAuth (SQLite) precisa de um volume persistente e de uma chave de criptografia fixa:

fly volumes create oauth_data --size 1 --region gru
fly secrets set OAUTH_ENCRYPTION_KEY=$(openssl rand -hex 32)

Isso já está configurado em fly.toml (OAUTH_DB_PATH=/data/oauth.db, montado no volume oauth_data). Localmente, se OAUTH_ENCRYPTION_KEY não estiver definida, uma chave é gerada e persistida ao lado do banco (oauth.key), com aviso no console.

Ferramentas

Nomes exatos das tools são os registrados no código (src/tools/); a lista completa aparece no cliente MCP ao conectar. Resumo por recurso:

Implementação: um arquivo por recurso em src/tools/ (ex.: src/tools/checkouts.ts).

Notas importantes de negócio, refletidas nas ferramentas:

• Reembolsos (refund*) são sempre integrais — a API v2 não suporta reembolso parcial.

• checkTransparentPix e simulateTransparentPixPayment funcionam apenas para PIX; boleto não tem simulação de pagamento.

• simulateTransparentPixPayment só funciona com uma chave de teste (modo dev).

• listPixTransactions/getPixTransaction exigem id; a API não pagina nem filtra por status nesse endpoint.

• changeSubscriptionPlan e cancelSubscription são irreversíveis; não há suporte a pró-rata no cancelamento.

Ideias de prompts

• Produto + checkout: "Crie um produto 'Consultoria' de R$ 150 e um checkout PIX+cartão para ele."

• Cupom para campanha: "Crie um cupom 15% com código ALEX15, máximo 100 usos."

• Conferir vendas: "Liste os checkouts pagos dos últimos 7 dias e resuma valores."

• Assinatura: "Crie um produto mensal de R$ 49 e uma assinatura para o cliente X."

Problemas comuns

Contribuição e licença

• Contribuição: CONTRIBUTING.md

• Licença: LICENSE (MIT)