# xendit-mcp (read-only)

Minimal, read-only MCP server for Xendit. Built for the CareNow Issue Resolver agent — looks up payments, disbursements, refunds, and VA transactions. **Never moves money.**

Unofficial. Not affiliated with or endorsed by Xendit.

## Why read-only?

Agents should not be able to call `create_disbursement`, `create_refund`, or `expire_invoice` — even via prompt injection from a Xendit-side field. This server exposes **only GET endpoints**. For defense in depth, also use a Xendit API key scoped to `*_READ` permissions.

## Install & run

No clone required. Install directly from GitHub via `npx`:

```json
{
  "mcpServers": {
    "xendit": {
      "command": "npx",
      "args": ["-y", "github:indratjhai/xendit-mcp"],
      "env": {
        "XENDIT_API_KEY": "xnd_development_..."
      }
    }
  }
}
```

On first run, npm clones the repo, installs deps, and runs `npm run build` via the `prepare` script. After that it launches from the cached install.

Pin a specific commit for reproducibility:

```
"args": ["-y", "github:indratjhai/xendit-mcp#<commit-sha>"]
```

### Local development

```bash
git clone https://github.com/indratjhai/xendit-mcp.git
cd xendit-mcp
npm install
cp .env.example .env  # fill in XENDIT_API_KEY
npm run dev
```

## API key

1. Go to https://dashboard.xendit.co/settings/developers#api-keys
2. Create a key with **READ-only** permissions:
   - `BALANCE_READ`
   - `INVOICE_READ`
   - `TRANSACTION_READ`
   - `DISBURSEMENT_READ`
   - `REFUND_READ`
   - `PAYMENT_REQUEST_READ`
3. Use a `xnd_development_...` test key while developing.

## Tools

| Tool | Purpose |
|---|---|
| `xendit_get_balance` | Account balance by type (CASH / HOLDING / TAX) |
| `xendit_list_invoices` | Filter by external_id, status, date range |
| `xendit_get_invoice` | Invoice by ID |
| `xendit_list_transactions` | Core tool — filter by reference_id, type, channel, date |
| `xendit_get_transaction` | Transaction by ID |
| `xendit_get_disbursement` | Disbursement by ID |
| `xendit_get_disbursement_by_external_id` | Disbursement by your reference |
| `xendit_list_refunds` | Filter by payment_request_id / invoice_id / reference_id |
| `xendit_get_refund` | Refund by ID |
| `xendit_list_payment_requests` | New Payments API — filter by reference_id |
| `xendit_get_payment_request` | Payment request by ID |
| `xendit_get_fixed_va` | Virtual account — for Wrong VA investigations |
| `xendit_get_va_payment` | VA payment by payment_id |

## What's not here (by design)

- `create_invoice`, `expire_invoice`
- `create_disbursement`
- `create_refund`
- `create_payment_request`
- Any POST / PATCH / DELETE

If a workflow needs a mutation, it should be done manually in the Xendit dashboard or via a separate approval flow that a human reviews — not from an agent session.

## Security notes

- API key read from `XENDIT_API_KEY` env var. Never logged, never sent to tool output.
- Network egress is hardcoded to `https://api.xendit.co` — no other hosts.
- Path-component IDs are validated against `^[a-zA-Z0-9_-]+$` and URL-encoded.
- All tool inputs are zod-validated.
- Only runtime deps: `@modelcontextprotocol/sdk`, `zod`.

## License

MIT