xendit-mcp

xendit-mcp

Servidor Model Context Protocol para a API de pagamentos Xendit. Suporta links de pagamento via faturas, pagamentos/transferências, saldos e transações na Indonésia, Filipinas, Tailândia, Vietnã e Malásia.

Instalação

npm install -g xendit-mcp

Ou execute sob demanda com npx xendit-mcp.

Atualização da versão 0.1.x

A versão 0.2.0 introduz padrões que quebram a compatibilidade. Se você estava na versão 0.1.x e dependia da criação de faturas ou pagamentos únicos funcionando imediatamente, essas ferramentas agora estão desabilitadas por padrão.

Para restaurar o comportamento antigo, defina estas opções na sua configuração MCP env:

XENDIT_ENABLE_INVOICE_MUTATIONS=true
XENDIT_ENABLE_DISBURSEMENTS=true
XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true

Se você habilitar pagamentos, também deve definir os quatro bloqueios de segurança (XENDIT_MAX_DISBURSEMENT_AMOUNT, XENDIT_MAX_DAILY_AMOUNT, XENDIT_ALLOWED_ACCOUNTS, XENDIT_APPROVAL_CODE) ou o servidor se recusará a iniciar.

A migração recomendada é adotar o novo fluxo de pagamento em duas etapas (prepare_disbursement → confirm_disbursement com um código de aprovação) em vez de reativar o pagamento único legado. Consulte Segurança para detalhes.

Modos voltados ao usuário

Pense no produto em 3 modos:

• read-only: saldos, leitura de faturas, leitura de transações
• invoices: somente leitura mais create_invoice e expire_invoice
• guarded-payouts: modo de faturas mais prepare_disbursement e confirm_disbursement

Para usuários não técnicos, os auxiliares mais fáceis são:

npx xendit-mcp doctor
npx xendit-mcp setup

• doctor exibe o modo atual, os recursos habilitados e o que ainda está bloqueado.
• setup gera um trecho de configuração para Claude Code ou Claude Desktop no modo desejado.

Configuração

1. Cadastre-se no Painel Xendit.
2. Vá em Configurações → Chaves de API e gere uma chave.
3. Use uma chave de teste (xnd_development_...) para desenvolvimento ou uma chave ao vivo para produção.

Variável	Obrigatória	Descrição
XENDIT_API_KEY	sim	Chave de API de teste ou ao vivo
XENDIT_ENABLE_INVOICE_MUTATIONS	não	Defina como true para habilitar create_invoice, expire_invoice e o prompt create_payment_link. Desabilitado por padrão para um comportamento mais seguro somente leitura.
XENDIT_ENABLE_DISBURSEMENTS	não	Defina como true para habilitar ferramentas de pagamento (movimentação de dinheiro). Desabilitado por padrão.
XENDIT_ALLOW_LIVE	não	Defina como true para permitir chaves ao vivo/de produção (prefixos xnd_production_, iluma_production_, sk_live_). Recusado por padrão.
XENDIT_MAX_DISBURSEMENT_AMOUNT	não	Limite máximo para uma única chamada de saída de dinheiro. Defina como 0 ou omita para desabilitar.
XENDIT_MAX_DAILY_AMOUNT	não	Limite contínuo de 24 horas para chamadas de saída de dinheiro. Defina como 0 ou omita para desabilitar.
XENDIT_ALLOWED_ACCOUNTS	não	Lista de permissões separada por vírgulas no formato CHANNEL_CODE:ACCOUNT_NUMBER, ex.: ID_BCA:1234567890.
XENDIT_PREPARE_TTL_SECONDS	não	Por quanto tempo um token de pagamento preparado permanece válido. Padrão: 300, máximo: 86400.
XENDIT_APPROVAL_CODE	não	Obrigatório quando XENDIT_ENABLE_DISBURSEMENTS=true. Código de aprovação humana exigido por confirm_disbursement e pagamentos únicos legados. Mantenha-o fora de contextos de prompt não confiáveis.
XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT	não	Defina como true somente se você quiser intencionalmente a ferramenta antiga de pagamento único create_disbursement. Desabilitado por padrão.

Configuração guiada

Se você não quiser editar manualmente as variáveis de ambiente, execute:

npx xendit-mcp setup

Ele perguntará qual cliente você usa e qual modo deseja, e então exibirá um trecho de configuração Claude pronto para colar, com espaços reservados para segredos.

Se o MCP já estiver conectado no Claude, você também pode pedir ao Claude para usar:

• get_workspace_mode
• guided_setup

guided_setup usa elicitação MCP no Claude Code quando disponível, para que o usuário veja um formulário em vez de detalhes brutos de configuração.

Claude Desktop

Edite claude_desktop_config.json:

{
  "mcpServers": {
    "xendit": {
      "command": "npx",
      "args": ["-y", "xendit-mcp"],
      "env": {
        "XENDIT_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add xendit --env XENDIT_API_KEY=your-api-key -- npx -y xendit-mcp

Cursor

Adicione a ~/.cursor/mcp.json com o mesmo formato do Claude Desktop.

Ferramentas

Ferramenta	Descrição
get_workspace_mode	Explica qual modo Xendit está ativo, o que está habilitado e o próximo passo mais seguro para desbloquear mais recursos.
guided_setup	Gera um trecho de configuração Claude Code ou Claude Desktop para read-only, invoices ou guarded-payouts.
get_balance	Saldo da conta por tipo (CASH, HOLDING, TAX).
list_invoices	Lista faturas filtradas por status, intervalo de datas ou moeda.
get_invoice	Recupera uma única fatura.
create_invoice	Cria uma fatura de pagamento e retorna um link de pagamento. Desabilitada a menos que XENDIT_ENABLE_INVOICE_MUTATIONS=true.
expire_invoice	Expira uma fatura ativa. Desabilitada a menos que XENDIT_ENABLE_INVOICE_MUTATIONS=true.
list_transactions	Lista pagamentos, transferências, reembolsos, transferências e ajustes de saldo.
prepare_disbursement	Prepara uma chamada de saída de dinheiro e retorna um token de confirmação de curta duração. Desabilitada a menos que XENDIT_ENABLE_DISBURSEMENTS=true.
confirm_disbursement	Executa um token de saída de dinheiro previamente preparado. Exige approvalCode. Desabilitada a menos que XENDIT_ENABLE_DISBURSEMENTS=true.
cancel_disbursement	Cancela um token de saída de dinheiro preparado. Desabilitada a menos que XENDIT_ENABLE_DISBURSEMENTS=true.
create_disbursement	Pagamento/transferência única legada. Exige approvalCode e aceitação explícita do legado. Desabilitada a menos que XENDIT_ENABLE_DISBURSEMENTS=true e XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true.
get_disbursement	Verifica o status do pagamento/transferência. Desabilitada a menos que XENDIT_ENABLE_DISBURSEMENTS=true.
list_disbursement_banks	Lista canais de pagamento como ID_BCA e PH_BPI. Desabilitada a menos que XENDIT_ENABLE_DISBURSEMENTS=true.

Prompts

Prompt	Descrição
check_balance	Relata o saldo da conta.
recent_payments	Pagamentos recebidos nos últimos N dias.
create_payment_link	Gera um link de pagamento para um cliente. Desabilitado a menos que XENDIT_ENABLE_INVOICE_MUTATIONS=true.
unpaid_invoices	Lista faturas pendentes.
daily_summary	Atividade de pagamentos de hoje.

Recursos

Recurso	URI	Descrição
Bancos suportados	xendit://banks	Aliases comuns de canais de pagamento para Indonésia e Filipinas.
Guia de configuração	xendit://setup	Modo atual, comandos de configuração e explicações dos modos em linguagem simples.
Informações da API	xendit://info	Visão geral da API Xendit e links de documentação.

Exemplos de consultas

What's my current Xendit balance?
Saldo Xendit saya berapa?

With `XENDIT_ENABLE_INVOICE_MUTATIONS=true`:
Create an invoice for Rp 500,000 for "Website design deposit".
Buatkan invoice Rp 500.000 untuk "Deposit desain website".

Show me all unpaid invoices.
Tampilkan semua invoice yang belum dibayar.

Com XENDIT_ENABLE_DISBURSEMENTS=true:

Prepare a Rp 1,000,000 payout to Ahmad at BCA, then wait for my confirmation.
Siapkan payout Rp 1.000.000 ke Ahmad di BCA, lalu tunggu konfirmasi saya.

List available payout channels in the Philippines.

Ambientes

A Xendit emite chaves de API separadas para teste e produção. As chaves de teste operam contra o sandbox da Xendit, portanto nenhum dinheiro real é movimentado. As chaves ao vivo (xnd_production_..., iluma_production_..., sk_live_...) operam contra a produção.

Segurança

Este servidor pode movimentar dinheiro real por meio da API Xendit. Principais salvaguardas:

• Somente leitura por padrão. As ferramentas de escrita de faturas estão desabilitadas a menos que XENDIT_ENABLE_INVOICE_MUTATIONS=true. As ferramentas de movimentação de dinheiro estão desabilitadas a menos que XENDIT_ENABLE_DISBURSEMENTS=true.
• Chaves ao vivo são recusadas por padrão. Chaves com os prefixos xnd_production_, iluma_production_ ou sk_live_ são rejeitadas na inicialização a menos que XENDIT_ALLOW_LIVE=true. Sempre teste primeiro com uma chave de desenvolvimento (xnd_development_...).
• Movimentação de dinheiro com falha segura. Se você habilitar pagamentos, o servidor se recusa a iniciar a menos que XENDIT_MAX_DISBURSEMENT_AMOUNT, XENDIT_MAX_DAILY_AMOUNT, XENDIT_ALLOWED_ACCOUNTS e XENDIT_APPROVAL_CODE estejam configurados.
• Fluxo com intervenção humana. confirm_disbursement exige tanto o token preparado quanto um approvalCode separado.
• Pagamentos únicos legados permanecem desabilitados por padrão. create_disbursement nem é registrado a menos que XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true.
• Limites máximos e listas de permissões. XENDIT_MAX_DISBURSEMENT_AMOUNT, XENDIT_MAX_DAILY_AMOUNT e XENDIT_ALLOWED_ACCOUNTS permitem falha segura antes do envio de um pagamento.
• Idempotência. Chamadas de pagamento usam seu externalId como o Idempotency-Key, portanto novas tentativas seguras não criam transferências duplicadas.
• Auxiliares de configuração sempre disponíveis. get_workspace_mode e guided_setup são expostos mesmo no modo somente leitura para que os usuários entendam o que está bloqueado e como habilitar o próximo modo com segurança.
• Limitação importante. Nenhum servidor MCP pode ser totalmente imune a injeção de prompt se você expor ferramentas sensíveis de leitura ou escrita a um contexto de modelo não confiável. Esses padrões reduzem o risco, mas você ainda deve conectar este servidor apenas a fluxos de trabalho de agentes confiáveis.

Mesmo com esses bloqueios ativados, revise qualquer solicitação de movimentação de dinheiro antes de aprovar a chamada da ferramenta. Trate entradas de ferramentas derivadas da saída do modelo como não confiáveis.

Ciclo de vida de um pagamento

Um pagamento confirmado nem sempre é bem-sucedido ou falha imediatamente. A Xendit retorna um destes status, e o estado final pode chegar segundos ou minutos depois:

• ACCEPTED — aceito pela Xendit, processamento do canal em andamento
• REQUESTED — enviado ao canal de destino, aguardando a resposta do canal
• SUCCEEDED — fundos entregues
• FAILED — falha final (ex.: INVALID_DESTINATION, REJECTED_BY_CHANNEL, INSUFFICIENT_BALANCE)

Alguns destinos (observados em testes no sandbox PHP) permanecem em REQUESTED por um tempo antes de transicionar para FAILED. Sempre consulte novamente com get_disbursement antes de assumir o estado final. Não trate a resposta inicial de confirm_disbursement como prova de entrega.

Escopo de verificação no sandbox

A versão 0.2.0 foi verificada no sandbox da Xendit usando chaves de desenvolvimento IDR e PHP (25 de maio de 2026). Fluxos verificados:

• Criar / obter / listar / expirar fatura (IDR + PHP)
• Descoberta de canais de pagamento (PHP)
• Pagamento protegido prepare → confirm → get (IDR + PHP)
• Motivos negativos de pagamento INVALID_DESTINATION e REJECTED_BY_CHANNEL (somente PHP — a chave do sandbox IDR tinha balance: 0, então os casos negativos em IDR apareceram como INSUFFICIENT_BALANCE em vez de falhas específicas do destino)

O comportamento na Tailândia, Vietnã e Malásia ainda não foi verificado com chaves reais de sandbox. O comportamento deve ser semelhante, mas não pode ser declarado como testado.

Endurecimento opcional do Claude Code

O Claude Code suporta hooks PreToolUse que podem forçar uma caixa de diálogo de aprovação extra para ferramentas sensíveis, como confirm_disbursement. Isso oferece um segundo controle fora do contexto do modelo.

Exemplo de trecho .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__xendit__confirm_disbursement",
        "hooks": [
          {
            "type": "command",
            "command": "printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"Human review required before confirm_disbursement.\"}}'"
          }
        ]
      }
    ]
  }
}

Aviso legal

Este é um servidor MCP não oficial, construído pela comunidade. Não é afiliado, endossado ou patrocinado pela Xendit. Xendit é uma marca registrada de seus respectivos proprietários. Use por sua conta e risco. O autor não aceita responsabilidade por fundos perdidos devido a uso indevido, injeção de prompt ou bugs.

Licença

MIT