xendit-mcp

Model Context Protocol server for the Xendit payment API. Supports payment links via invoices, payouts/disbursements, balances, and transactions across Indonesia, the Philippines, Thailand, Vietnam, and Malaysia.

Install

npm install -g xendit-mcp

Or run on demand with npx xendit-mcp.

Upgrading from 0.1.x

0.2.0 introduces breaking defaults. If you were on 0.1.x and relied on invoice creation or one-shot payouts working out of the box, those tools are now disabled by default.

To restore the old behavior, set these in your MCP config env:

XENDIT_ENABLE_INVOICE_MUTATIONS=true
XENDIT_ENABLE_DISBURSEMENTS=true
XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true

If you enable disbursements, you must also set the four safety gates (XENDIT_MAX_DISBURSEMENT_AMOUNT, XENDIT_MAX_DAILY_AMOUNT, XENDIT_ALLOWED_ACCOUNTS, XENDIT_APPROVAL_CODE) or the server will refuse to start.

The recommended migration is to adopt the new two-step payout flow (prepare_disbursement → confirm_disbursement with an approval code) instead of re-enabling the legacy one-shot. See Safety for details.

User-facing modes

Think about the product in 3 modes:

• read-only: balances, invoices read, transactions read
• invoices: read-only plus create_invoice and expire_invoice
• guarded-payouts: invoices mode plus prepare_disbursement and confirm_disbursement

For non-technical users, the easiest helpers are:

npx xendit-mcp doctor
npx xendit-mcp setup

• doctor prints the current mode, enabled capabilities, and what is still blocked.
• setup generates a Claude Code or Claude Desktop snippet for the mode you want.

Configuration

1. Sign up at the Xendit Dashboard.
2. Go to Settings → API Keys and generate a key.
3. Use a test key (xnd_development_...) for development or a live key for production.

Guided setup

If you do not want to hand-edit env vars, run:

npx xendit-mcp setup

It will ask which client you use and which mode you want, then output a ready-to-paste Claude config snippet with placeholders for secrets.

If the MCP is already connected in Claude, you can also ask Claude to use:

• get_workspace_mode
• guided_setup

guided_setup uses MCP elicitation in Claude Code when available, so the user sees a form instead of raw config details.

Claude Desktop

Edit 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

Add to ~/.cursor/mcp.json with the same shape as Claude Desktop.

Tools

Prompts

Resources

Example queries

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.

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

Environments

Xendit issues separate test and live API keys. Test keys operate against the Xendit sandbox, so no real funds move. Live keys (xnd_production_..., iluma_production_..., sk_live_...) operate against production.

Safety

This server can move real money through the Xendit API. Key safeguards:

• Read-only by default. Invoice write tools are disabled unless XENDIT_ENABLE_INVOICE_MUTATIONS=true. Money-moving tools are disabled unless XENDIT_ENABLE_DISBURSEMENTS=true.
• Live keys are refused by default. Keys with the prefixes xnd_production_, iluma_production_, or sk_live_ are rejected at startup unless XENDIT_ALLOW_LIVE=true. Always test with a development key (xnd_development_...) first.
• Fail-closed money movement. If you enable disbursements, the server refuses to start unless XENDIT_MAX_DISBURSEMENT_AMOUNT, XENDIT_MAX_DAILY_AMOUNT, XENDIT_ALLOWED_ACCOUNTS, and XENDIT_APPROVAL_CODE are configured.
• Human-in-the-loop flow. confirm_disbursement requires both the staged token and a separate approvalCode.
• Legacy one-shot payouts stay off by default. create_disbursement is not even registered unless XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true.
• Hard caps and allowlists. XENDIT_MAX_DISBURSEMENT_AMOUNT, XENDIT_MAX_DAILY_AMOUNT, and XENDIT_ALLOWED_ACCOUNTS let you fail closed before a payout is sent.
• Idempotency. Payout calls use your externalId as the Idempotency-Key, so safe retries do not create duplicate transfers.
• Setup helpers are always available. get_workspace_mode and guided_setup are exposed even in read-only mode so users can understand what is blocked and how to enable the next mode safely.
• Important limitation. No MCP server can be fully immune to prompt injection if you expose sensitive read or write tools to an untrusted model context. These defaults reduce risk, but you should still only connect this server to trusted agent workflows.

Even with these gates on, review any money-moving request before approving the tool call. Treat tool inputs derived from model output as untrusted.

Payout lifecycle

A confirmed payout does not always succeed or fail immediately. Xendit returns one of these statuses, and the terminal state may arrive seconds or minutes later:

• ACCEPTED — accepted by Xendit, channel processing in progress
• REQUESTED — submitted to the destination channel, waiting for the channel's response
• SUCCEEDED — funds delivered
• FAILED — final failure (e.g. INVALID_DESTINATION, REJECTED_BY_CHANNEL, INSUFFICIENT_BALANCE)

Some destinations (observed in PHP sandbox testing) sit in REQUESTED for a while before transitioning to FAILED. Always re-fetch with get_disbursement before assuming the final state. Do not treat the initial response from confirm_disbursement as proof of delivery.

Sandbox verification scope

0.2.0 was verified against the Xendit sandbox using IDR and PHP development keys (May 25, 2026). Verified flows:

• Invoice create / get / list / expire (IDR + PHP)
• Payout channel discovery (PHP)
• Guarded payout prepare → confirm → get (IDR + PHP)
• Negative payout reasons INVALID_DESTINATION and REJECTED_BY_CHANNEL (PHP only — the IDR sandbox key had balance: 0, so negative IDR cases surfaced as INSUFFICIENT_BALANCE rather than destination-specific failures)

Thailand, Vietnam, and Malaysia behavior is not yet verified against real sandbox keys. Behavior should be similar but cannot be claimed as tested.

Optional Claude Code hardening

Claude Code supports PreToolUse hooks that can force an extra approval dialog for sensitive tools such as confirm_disbursement. That gives you a second control outside the model context.

Example .claude/settings.json snippet:

{
  "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.\"}}'"
          }
        ]
      }
    ]
  }
}

Disclaimer

This is an unofficial, community-built MCP server. Not affiliated with, endorsed by, or sponsored by Xendit. Xendit is a trademark of its respective owners. Use at your own risk. The author accepts no liability for funds lost through misuse, prompt injection, or bugs.

License

MIT