payments-mcp

MCP Server (Model Context Protocol) para centralizar integrações de pagamento:

• Pagar.me (Core API v5): customers, recipients, Pix, cartão, split 100%, charges, captura/cancelamento, tokenização (card_token)

• Woovi/OpenPix: charges Pix, consulta/listagem, deleção, refunds, verificação de webhook (HMAC)

O servidor expõe tools MCP para serem chamadas por um client MCP (ex: um agente/LLM), via stdio (padrão) ou MCP over HTTP (opcional).

Licença

MIT - Veja: ./LICENSE.

Stack e arquitetura

• Node.js + TypeScript

• MCP TypeScript SDK (@modelcontextprotocol/sdk) usando o McpServer com registerTool e schemas Zod.

• Zod para validação de entrada

• Axios para Woovi/OpenPix

• SDK oficial Pagar.me @pagarme/pagarme-nodejs-sdk

• Express (opcional): para expor MCP over HTTP (/mcp) via StreamableHTTPServerTransport

Estrutura de pastas (clean, por domínio):

• src/index.ts: bootstrap do MCP server (stdio)

• src/http/server.ts: transport HTTP opcional (MCP over HTTP)

• src/mcp/server.ts: factory de criação do McpServer (tools registradas)

• src/tools/register.ts: registry central de tools

• src/mcp/utils.ts: helpers de resposta/erro (ok, fail)

• src/integrations/pagarme/*: client, schemas e tools Pagar.me

• src/integrations/woovi/*: client, schemas e tools Woovi/OpenPix

Requisitos

• Node.js 18+ (recomendado) / npm

• Credenciais de Pagar.me e/ou Woovi/OpenPix

Instalação

Build:

Rodar (stdio):

Dev:

Observação: o build sempre limpa dist/ antes de compilar.

Variáveis de ambiente

Crie um .env na raiz (ou exporte no ambiente):

Copie o template:

Pagar.me

• PAGARME_API_KEY (obrigatória): usada como Basic Auth username (password vazio)

• PAGARME_PUBLIC_KEY (opcional, mas recomendado): necessária para pagarme_create_card_token / pagarme_get_token

Woovi/OpenPix

• WOOVI_APP_ID (obrigatória): header Authorization (AppID)

• WOOVI_BASE_URL (opcional):

  • produção: https://api.openpix.com.br/api/v1 (default)

  • sandbox: https://api.woovi-sandbox.com/api/v1

Modos de execução (MCP)

MCP via stdio (local)

Modo padrão (ex: Cursor). O client MCP executa este processo e conversa via stdin/stdout.

MCP over HTTP (opcional)

Se você definir MCP_HTTP_PORT, o servidor também expõe MCP via HTTP (Streamable HTTP).

Exemplo:

Endpoints:

• GET /health

• POST /mcp (protocolo MCP)

• GET /mcp (protocolo MCP, com sessão)

• DELETE /mcp (protocolo MCP, com sessão)

Importante: isso é MCP over HTTP, não é uma REST API para o frontend.

Para usar via HTTP, utilize um client MCP HTTP (ex: StreamableHTTPClientTransport). O servidor usa sessões via header mcp-session-id (o client gerencia isso automaticamente).

Exemplo (TypeScript) de client MCP HTTP:

Rodar com Docker

Build da imagem

Subir como serviço (MCP over HTTP)

Opção 1 (docker run):

Opção 2 (docker compose):

Health check:

Rodar E2E dentro do container

Smoke:

Full:

Pagar.me — funcionalidades (tools MCP)

Customers

• pagarme_create_customer

• pagarme_get_customer

• pagarme_update_customer_metadata

Recipients (personal)

• pagarme_create_recipient

• pagarme_update_recipient_default_bank_account

• pagarme_get_recipients

Orders / Pix / Cartão (split 100%)

• pagarme_get_order

• pagarme_create_order_pix_split

• pagarme_create_order_credit_card_split

Split 100%:

• O recipient (personal) recebe 100% do valor do pedido e arcará com as taxas (configurado como liable=true e chargeProcessingFee=true no split do payment).

Charges

• pagarme_get_charge

• pagarme_get_charge_transactions (útil para Pix — QRCode vem das transações)

• pagarme_capture_charge (quando cartão foi criado com capture=false)

• pagarme_cancel_charge

Tokenização (cartão)

• pagarme_create_card_token (usa PAGARME_PUBLIC_KEY ou publicKey no payload)

• pagarme_get_token

Woovi/OpenPix — funcionalidades (tools MCP)

As tools foram implementadas seguindo a documentação do OpenPix (Woovi), incluindo:

Charges (Pix)

• woovi_create_charge (POST /api/v1/charge)

• woovi_get_charge (GET /api/v1/charge/{id})

• woovi_list_charges (GET /api/v1/charge com filtros)

• woovi_delete_charge (DELETE /api/v1/charge/{id})

Saída “pronta para FrontEnd”:

As tools woovi_create_charge e woovi_get_charge retornam um objeto normalizado com:

• charge.brCode

• charge.qrCodeImage

• charge.paymentLinkUrl

• charge.expiresDate

• charge.status

• e raw com o payload integral da API

Refunds

• woovi_create_refund (POST /api/v1/refund)

• woovi_list_refunds (GET /api/v1/refund)

• woovi_get_refund (GET /api/v1/refund/{id})

• woovi_get_charge_refunds (GET /api/v1/charge/{id}/refund)

• woovi_create_charge_refund (POST /api/v1/charge/{id}/refund)

Webhook

• woovi_verify_webhook_hmac: valida HMAC do webhook usando sha1 + base64 e o header X-OpenPix-Signature.

Fluxos recomendados

Pix via Pagar.me (preferência atual)

1. (opcional) pagarme_create_customer (aluno)

2. pagarme_create_recipient (personal)

3. pagarme_create_order_pix_split → retorna chargeId e pix.qrCode/qrCodeUrl/expiresAt

4. Polling de status com pagarme_get_charge / pagarme_get_order

Pix via Woovi/OpenPix (alternativo)

1. woovi_create_charge → retorna charge.brCode, charge.qrCodeImage, charge.paymentLinkUrl

2. woovi_get_charge / woovi_list_charges → acompanhar status

3. Se precisar estornar: woovi_create_refund (com transactionEndToEndId)

Cartão via Pagar.me

1. (opcional) pagarme_create_card_token → obtém card_token

2. pagarme_create_order_credit_card_split (usa cardToken ou cardId)

3. Se capture=false: pagarme_capture_charge

4. Cancelamento/estorno: pagarme_cancel_charge

Exemplos de payloads (copiar/colar)

Pagar.me — Pix + split 100%

Pagar.me — tokenização (card_token)

Pagar.me — Cartão + split 100%

Woovi/OpenPix — criar charge Pix

Woovi/OpenPix — refund

Woovi/OpenPix — validar webhook (HMAC)

Referências (Context7)

• OpenPix/Woovi — charges/refunds/webhook HMAC: developers_openpix_br (docs em api.md e docs/webhook/seguranca/webhook-hmac.md)

• Pagar.me — SDK Node: pagarme/pagarme-nodejs-sdk

• MCP TypeScript SDK: modelcontextprotocol/typescript-sdk

Autor

Luiz Pillon.