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

Terminal

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:

Code

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:

Terminal

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

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

Variable	Required	Description
`XENDIT_API_KEY`	yes	Test or live API key
`XENDIT_ENABLE_INVOICE_MUTATIONS`	no	Set to `true` to enable `create_invoice`, `expire_invoice`, and the `create_payment_link` prompt. Disabled by default for safer read-only behavior.
`XENDIT_ENABLE_DISBURSEMENTS`	no	Set to `true` to enable disbursement tools (money-movement). Disabled by default.
`XENDIT_ALLOW_LIVE`	no	Set to `true` to allow live/production keys (prefixes `xnd_production_`, `iluma_production_`, `sk_live_`). Refused by default.
`XENDIT_MAX_DISBURSEMENT_AMOUNT`	no	Hard cap for one money-out call. Set to `0` or omit to disable.
`XENDIT_MAX_DAILY_AMOUNT`	no	Rolling 24-hour cap across money-out calls. Set to `0` or omit to disable.
`XENDIT_ALLOWED_ACCOUNTS`	no	Comma-separated allowlist in `CHANNEL_CODE:ACCOUNT_NUMBER` format, e.g. `ID_BCA:1234567890`.
`XENDIT_PREPARE_TTL_SECONDS`	no	How long a prepared disbursement token stays valid. Defaults to `300`, max `86400`.
`XENDIT_APPROVAL_CODE`	no	Required when `XENDIT_ENABLE_DISBURSEMENTS=true`. Human approval code required by `confirm_disbursement` and legacy one-shot payouts. Keep it out of untrusted prompt context.
`XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT`	no	Set to `true` only if you intentionally want the old `create_disbursement` one-shot tool. Disabled by default.

Guided setup

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

Terminal

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:

config.json

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

Claude Code

Terminal

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

Tool	Description
`get_workspace_mode`	Explain which Xendit mode is active, what is enabled, and the safest next step to unlock more features.
`guided_setup`	Generate a Claude Code or Claude Desktop config snippet for `read-only`, `invoices`, or `guarded-payouts`.
`get_balance`	Account balance by type (CASH, HOLDING, TAX).
`list_invoices`	List invoices filtered by status, date range, or currency.
`get_invoice`	Retrieve a single invoice.
`create_invoice`	Create a payment invoice and return a payment link. Disabled unless `XENDIT_ENABLE_INVOICE_MUTATIONS=true`.
`expire_invoice`	Expire an active invoice. Disabled unless `XENDIT_ENABLE_INVOICE_MUTATIONS=true`.
`list_transactions`	List payments, payouts, refunds, transfers, and balance adjustments.
`prepare_disbursement`	Stage a money-out call and return a short-lived confirmation token. Disabled unless `XENDIT_ENABLE_DISBURSEMENTS=true`.
`confirm_disbursement`	Execute a previously prepared money-out token. Requires `approvalCode`. Disabled unless `XENDIT_ENABLE_DISBURSEMENTS=true`.
`cancel_disbursement`	Cancel a prepared money-out token. Disabled unless `XENDIT_ENABLE_DISBURSEMENTS=true`.
`create_disbursement`	Legacy one-shot payout/disbursement. Requires `approvalCode` and explicit legacy opt-in. Disabled unless both `XENDIT_ENABLE_DISBURSEMENTS=true` and `XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true`.
`get_disbursement`	Check payout/disbursement status. Disabled unless `XENDIT_ENABLE_DISBURSEMENTS=true`.
`list_disbursement_banks`	List payout channels such as `ID_BCA` and `PH_BPI`. Disabled unless `XENDIT_ENABLE_DISBURSEMENTS=true`.

Prompts

Prompt	Description
`check_balance`	Report account balance.
`recent_payments`	Payments received in the last N days.
`create_payment_link`	Generate a payment link for a customer. Disabled unless `XENDIT_ENABLE_INVOICE_MUTATIONS=true`.
`unpaid_invoices`	List pending invoices.
`daily_summary`	Today's payment activity.

Resources

Resource	URI	Description
Supported Banks	`xendit://banks`	Common payout channel aliases for Indonesia and the Philippines.
Setup Guide	`xendit://setup`	Current mode, setup commands, and plain-English mode explanations.
API Info	`xendit://info`	Xendit API overview and doc links.

Example queries

Code

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:

Code

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:

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

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