xendit-mcp

Pasarela de pago Xendit para el Sudeste Asiático. Facturas, desembolsos, consultas de saldo y transferencias bancarias.

Documentación

xendit-mcp

Servidor del Model Context Protocol para la API de pagos de Xendit. Admite enlaces de pago mediante facturas, pagos/desembolsos, saldos y transacciones en Indonesia, Filipinas, Tailandia, Vietnam y Malasia.

Instalación

npm install -g xendit-mcp

O ejecútalo bajo demanda con npx xendit-mcp.

Actualización desde 0.1.x

0.2.0 introduce valores predeterminados que rompen compatibilidad. Si estabas en 0.1.x y dependías de la creación de facturas o de pagos únicos que funcionaran sin configuración adicional, esas herramientas ahora están deshabilitadas por defecto.

Para restaurar el comportamiento anterior, establece estos valores en tu configuración de MCP env:

XENDIT_ENABLE_INVOICE_MUTATIONS=true
XENDIT_ENABLE_DISBURSEMENTS=true
XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true

Si habilitas desembolsos, también debes configurar las cuatro compuertas de seguridad (XENDIT_MAX_DISBURSEMENT_AMOUNT, XENDIT_MAX_DAILY_AMOUNT, XENDIT_ALLOWED_ACCOUNTS, XENDIT_APPROVAL_CODE) o el servidor se negará a iniciar.

La migración recomendada es adoptar el nuevo flujo de pago en dos pasos (prepare_disbursement → confirm_disbursement con un código de aprobación) en lugar de reactivar el pago único heredado. Consulta Seguridad para más detalles.

Modos orientados al usuario

Piensa en el producto en 3 modos:

read-only: saldos, lectura de facturas, lectura de transacciones
invoices: solo lectura más create_invoice y expire_invoice
guarded-payouts: modo facturas más prepare_disbursement y confirm_disbursement

Para usuarios no técnicos, los asistentes más sencillos son:

npx xendit-mcp doctor
npx xendit-mcp setup

doctor imprime el modo actual, las capacidades habilitadas y lo que aún está bloqueado.
setup genera un fragmento de Claude Code o Claude Desktop para el modo que desees.

Configuración

Regístrate en el Panel de Xendit.
Ve a Configuración → Claves API y genera una clave.
Usa una clave de prueba (xnd_development_...) para desarrollo o una clave de producción para el entorno real.

Variable	Requerida	Descripción
`XENDIT_API_KEY`	sí	Clave API de prueba o producción
`XENDIT_ENABLE_INVOICE_MUTATIONS`	no	Establécelo en `true` para habilitar `create_invoice`, `expire_invoice` y el prompt `create_payment_link`. Deshabilitado por defecto para un comportamiento de solo lectura más seguro.
`XENDIT_ENABLE_DISBURSEMENTS`	no	Establécelo en `true` para habilitar las herramientas de desembolso (movimiento de dinero). Deshabilitado por defecto.
`XENDIT_ALLOW_LIVE`	no	Establécelo en `true` para permitir claves de producción (prefijos `xnd_production_`, `iluma_production_`, `sk_live_`). Rechazado por defecto.
`XENDIT_MAX_DISBURSEMENT_AMOUNT`	no	Límite máximo para una sola llamada de salida de dinero. Establécelo en `0` u omítelo para deshabilitar.
`XENDIT_MAX_DAILY_AMOUNT`	no	Límite móvil de 24 horas para llamadas de salida de dinero. Establécelo en `0` u omítelo para deshabilitar.
`XENDIT_ALLOWED_ACCOUNTS`	no	Lista de permitidos separada por comas en formato `CHANNEL_CODE:ACCOUNT_NUMBER`, p. ej. `ID_BCA:1234567890`.
`XENDIT_PREPARE_TTL_SECONDS`	no	Cuánto tiempo permanece válido un token de desembolso preparado. Por defecto `300`, máximo `86400`.
`XENDIT_APPROVAL_CODE`	no	Requerido cuando `XENDIT_ENABLE_DISBURSEMENTS=true`. Código de aprobación humana requerido por `confirm_disbursement` y los pagos únicos heredados. Mantenlo fuera de contextos de prompt no confiables.
`XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT`	no	Establécelo en `true` solo si intencionalmente quieres la antigua herramienta de pago único `create_disbursement`. Deshabilitado por defecto.

Configuración guiada

Si no quieres editar manualmente las variables de entorno, ejecuta:

npx xendit-mcp setup

Preguntará qué cliente usas y qué modo deseas, y luego generará un fragmento de configuración de Claude listo para pegar, con marcadores de posición para los secretos.

Si el MCP ya está conectado en Claude, también puedes pedirle a Claude que use:

get_workspace_mode
guided_setup

guided_setup usa la elicitación de MCP en Claude Code cuando está disponible, por lo que el usuario ve un formulario en lugar de detalles de configuración en bruto.

Claude Desktop

Edita 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

Agrégalo a ~/.cursor/mcp.json con la misma estructura que Claude Desktop.

Herramientas

Herramienta	Descripción
`get_workspace_mode`	Explica qué modo de Xendit está activo, qué está habilitado y el siguiente paso más seguro para desbloquear más funciones.
`guided_setup`	Genera un fragmento de configuración de Claude Code o Claude Desktop para `read-only`, `invoices` o `guarded-payouts`.
`get_balance`	Saldo de la cuenta por tipo (CASH, HOLDING, TAX).
`list_invoices`	Lista facturas filtradas por estado, rango de fechas o moneda.
`get_invoice`	Recupera una sola factura.
`create_invoice`	Crea una factura de pago y devuelve un enlace de pago. Deshabilitada a menos que `XENDIT_ENABLE_INVOICE_MUTATIONS=true`.
`expire_invoice`	Expira una factura activa. Deshabilitada a menos que `XENDIT_ENABLE_INVOICE_MUTATIONS=true`.
`list_transactions`	Lista pagos, desembolsos, reembolsos, transferencias y ajustes de saldo.
`prepare_disbursement`	Prepara una llamada de salida de dinero y devuelve un token de confirmación de corta duración. Deshabilitada a menos que `XENDIT_ENABLE_DISBURSEMENTS=true`.
`confirm_disbursement`	Ejecuta un token de salida de dinero previamente preparado. Requiere `approvalCode`. Deshabilitada a menos que `XENDIT_ENABLE_DISBURSEMENTS=true`.
`cancel_disbursement`	Cancela un token de salida de dinero preparado. Deshabilitada a menos que `XENDIT_ENABLE_DISBURSEMENTS=true`.
`create_disbursement`	Pago/desembolso único heredado. Requiere `approvalCode` y aceptación explícita del modo heredado. Deshabilitada a menos que tanto `XENDIT_ENABLE_DISBURSEMENTS=true` como `XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true`.
`get_disbursement`	Consulta el estado del pago/desembolso. Deshabilitada a menos que `XENDIT_ENABLE_DISBURSEMENTS=true`.
`list_disbursement_banks`	Lista canales de pago como `ID_BCA` y `PH_BPI`. Deshabilitada a menos que `XENDIT_ENABLE_DISBURSEMENTS=true`.

Prompts

Prompt	Descripción
`check_balance`	Reporta el saldo de la cuenta.
`recent_payments`	Pagos recibidos en los últimos N días.
`create_payment_link`	Genera un enlace de pago para un cliente. Deshabilitado a menos que `XENDIT_ENABLE_INVOICE_MUTATIONS=true`.
`unpaid_invoices`	Lista facturas pendientes.
`daily_summary`	Actividad de pagos de hoy.

Recursos

Recurso	URI	Descripción
Bancos admitidos	`xendit://banks`	Alias comunes de canales de pago para Indonesia y Filipinas.
Guía de configuración	`xendit://setup`	Modo actual, comandos de configuración y explicaciones de modos en lenguaje sencillo.
Información de la API	`xendit://info`	Resumen de la API de Xendit y enlaces de documentación.

Consultas de ejemplo

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.

Con 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.

Entornos

Xendit emite claves API de prueba y de producción por separado. Las claves de prueba operan contra el sandbox de Xendit, por lo que no se mueve dinero real. Las claves de producción (xnd_production_..., iluma_production_..., sk_live_...) operan contra el entorno de producción.

Seguridad

Este servidor puede mover dinero real a través de la API de Xendit. Salvaguardas clave:

Solo lectura por defecto. Las herramientas de escritura de facturas están deshabilitadas a menos que XENDIT_ENABLE_INVOICE_MUTATIONS=true. Las herramientas de movimiento de dinero están deshabilitadas a menos que XENDIT_ENABLE_DISBURSEMENTS=true.
Las claves de producción se rechazan por defecto. Las claves con los prefijos xnd_production_, iluma_production_ o sk_live_ se rechazan al iniciar a menos que XENDIT_ALLOW_LIVE=true. Siempre prueba primero con una clave de desarrollo (xnd_development_...).
Movimiento de dinero con cierre seguro. Si habilitas desembolsos, el servidor se niega a iniciar a menos que XENDIT_MAX_DISBURSEMENT_AMOUNT, XENDIT_MAX_DAILY_AMOUNT, XENDIT_ALLOWED_ACCOUNTS y XENDIT_APPROVAL_CODE estén configurados.
Flujo con intervención humana. confirm_disbursement requiere tanto el token preparado como un approvalCode separado.
Los pagos únicos heredados permanecen deshabilitados por defecto. create_disbursement ni siquiera se registra a menos que XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true.
Límites máximos y listas de permitidos. XENDIT_MAX_DISBURSEMENT_AMOUNT, XENDIT_MAX_DAILY_AMOUNT y XENDIT_ALLOWED_ACCOUNTS te permiten cerrar de forma segura antes de enviar un pago.
Idempotencia. Las llamadas de pago usan tu externalId como Idempotency-Key, por lo que los reintentos seguros no crean transferencias duplicadas.
Los asistentes de configuración están siempre disponibles. get_workspace_mode y guided_setup se exponen incluso en modo de solo lectura para que los usuarios comprendan qué está bloqueado y cómo habilitar el siguiente modo de forma segura.
Limitación importante. Ningún servidor MCP puede ser completamente inmune a la inyección de prompts si expones herramientas sensibles de lectura o escritura a un contexto de modelo no confiable. Estos valores predeterminados reducen el riesgo, pero aun así solo debes conectar este servidor a flujos de trabajo de agentes confiables.

Incluso con estas compuertas activadas, revisa cualquier solicitud de movimiento de dinero antes de aprobar la llamada a la herramienta. Trata las entradas de herramientas derivadas de la salida del modelo como no confiables.

Ciclo de vida de un pago

Un pago confirmado no siempre tiene éxito o falla de inmediato. Xendit devuelve uno de estos estados, y el estado final puede llegar segundos o minutos después:

ACCEPTED — aceptado por Xendit, procesamiento del canal en curso
REQUESTED — enviado al canal de destino, esperando la respuesta del canal
SUCCEEDED — fondos entregados
FAILED — fallo definitivo (p. ej. INVALID_DESTINATION, REJECTED_BY_CHANNEL, INSUFFICIENT_BALANCE)

Algunos destinos (observado en pruebas con el sandbox de PHP) permanecen en REQUESTED durante un tiempo antes de pasar a FAILED. Siempre vuelve a consultar con get_disbursement antes de asumir el estado final. No trates la respuesta inicial de confirm_disbursement como prueba de entrega.

Alcance de la verificación en sandbox

0.2.0 se verificó contra el sandbox de Xendit usando claves de desarrollo IDR y PHP (25 de mayo de 2026). Flujos verificados:

Crear / obtener / listar / expirar facturas (IDR + PHP)
Descubrimiento de canales de pago (PHP)
Pago protegido prepare → confirm → get (IDR + PHP)
Razones de pago negativas INVALID_DESTINATION y REJECTED_BY_CHANNEL (solo PHP — la clave de sandbox IDR tenía balance: 0, por lo que los casos negativos en IDR aparecieron como INSUFFICIENT_BALANCE en lugar de fallos específicos del destino)

El comportamiento en Tailandia, Vietnam y Malasia aún no está verificado con claves de sandbox reales. El comportamiento debería ser similar, pero no se puede afirmar que esté probado.

Endurecimiento opcional de Claude Code

Claude Code admite hooks de PreToolUse que pueden forzar un diálogo de aprobación adicional para herramientas sensibles como confirm_disbursement. Eso te da un segundo control fuera del contexto del modelo.

Ejemplo de fragmento de .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 es un servidor MCP no oficial, construido por la comunidad. No está afiliado, respaldado ni patrocinado por Xendit. Xendit es una marca comercial de sus respectivos propietarios. Úsalo bajo tu propio riesgo. El autor no acepta responsabilidad por fondos perdidos debido a mal uso, inyección de prompts o errores.

Licencia

MIT