【用途】 xendit-mcp 是一个用于 Xendit 支付 API 的模型上下文协议（MCP）服务器，面向东南亚市场（印度尼西亚、菲律宾、泰国、越南、马来西亚）。它让 AI 客户端（如 Claude Code、Claude Desktop、Cursor）可以调用 Xendit 的支付相关能力，包括通过发票生成支付链接、放款/付款、余额查询和交易查询。
【主要能力】 服务器以三种面向用户的模式组织功能：
- read-only（只读）：余额查询、发票读取、交易读取。
- invoices（发票模式）：在只读基础上增加 create_invoice 和 expire_invoice。
- guarded-payouts（受控放款）：在发票模式基础上增加 prepare_disbursement 和 confirm_disbursement。 此外提供面向非技术用户的辅助工具：doctor 用于打印当前模式、已启用能力以及仍被阻止的功能；setup 会根据所选模式生成 Claude Code 或 Claude Desktop 的配置片段。get_workspace_mode 和 guided_setup 在只读模式下也可用。guided_setup 在 Claude Code 中可用时会使用 MCP elicitation，让用户看到表单而非原始配置。
【使用方式】 需先在 Xendit Dashboard 注册，进入 Settings → API Keys 生成密钥，开发使用测试密钥（xnd_development_…），生产使用实时密钥。可通过 npx xendit-mcp 按需运行，或运行 setup 生成配置片段（会询问所用客户端与模式，并输出可粘贴的 Claude 配置片段，密钥以占位符表示）。也可手动编辑 claude_desktop_config.json；Cursor 则在 ~/.cursor/mcp.json 添加同样结构。 从 0.1.x 升级到 0.2.0 存在破坏性默认变更：发票创建与一次性放款工具默认被禁用。如需恢复旧行为，需在 MCP 配置 env 中设置相应开关。若启用放款，必须设置四个安全闸门（XENDIT_MAX_DISBURSEMENT_AMOUNT、XENDIT_MAX_DAILY_AMOUNT、XENDIT_ALLOWED_ACCOUNTS、XENDIT_APPROVAL_CODE），否则服务器拒绝启动。官方推荐迁移到新的两步放款流程（prepare_disbursement → confirm_disbursement，配合审批码）。
【安全机制】
- 默认只读：除非设置 XENDIT_ENABLE_INVOICE_MUTATIONS=true，否则发票写工具禁用；除非设置 XENDIT_ENABLE_DISBURSEMENTS=true，否则资金转移工具禁用。
- 默认拒绝实时密钥：以 xnd_production_、iluma_production_、sk_live_ 为前缀的密钥在启动时被拒绝，除非设置 XENDIT_ALLOW_LIVE=true。建议先用开发密钥（xnd_development_…）测试。
- 失败即关闭的资金转移：启用放款时，必须配置四个闸门变量，否则拒绝启动。
- 人在回路：confirm_disbursement 需要暂存令牌和单独的 approvalCode。
- 旧版一次性放款默认关闭：除非设置 XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true，否则 create_disbursement 不会注册。
- 硬性上限与白名单：通过 XENDIT_MAX_DISBURSEMENT_AMOUNT、XENDIT_MAX_DAILY_AMOUNT、XENDIT_ALLOWED_ACCOUNTS 在付款前失败即关闭。
- 幂等性：付款调用以 externalId 作为 Idempotency-Key，安全重试不会产生重复转账。 重要限制：若将敏感读写工具暴露给不受信任的模型上下文，任何 MCP 服务器都无法完全免疫提示注入。应仅连接可信的智能体工作流，并在批准资金转移工具调用前人工复核，将来自模型输出的工具输入视为不可信。
【放款生命周期】 确认放款不一定会立即成功或失败，Xendit 返回的状态包括：ACCEPTED（已接受，渠道处理中）、REQUESTED（已提交至目标渠道，等待响应）、SUCCEEDED（资金已送达）、FAILED（最终失败，如 INVALID_DESTINATION、REJECTED_BY_CHANNEL、INSUFFICIENT_BALANCE）。部分目标（在 PHP 沙箱测试中观察到）会在 REQUESTED 停留一段时间后转为 FAILED。应始终通过 get_disbursement 重新获取，不要把 confirm_disbursement 的初始响应当作送达证明。
【沙箱验证范围】 0.2.0 已使用 IDR 和 PHP 开发密钥针对 Xendit 沙箱验证，验证流程包括：发票创建/获取/列表/过期（IDR + PHP）、放款渠道发现（PHP）、受控放款 prepare → confirm → get（IDR + PHP）、负面放款原因 INVALID_DESTINATION 和 REJECTED_BY_CHANNEL（仅 PHP，IDR 沙箱密钥余额为 0，因此 IDR 负面情形表现为 INSUFFICIENT_BALANCE）。泰国、越南和马来西亚的行为尚未用真实沙箱密钥验证，行为应类似但不能声称已测试。
【可选加固】 Claude Code 支持 PreToolUse 钩子，可为 confirm_disbursement 等敏感工具强制弹出额外审批对话框，提供模型上下文之外的二次控制。
【声明】 这是非官方、社区构建的 MCP 服务器，与 Xendit 无关联、未获其认可或赞助。Xendit 是其各自所有者的商标。使用风险自负，作者不对因误用、提示注入或缺陷导致的资金损失承担责任。
