当前位置：首页 > news >正文

基于MCP协议构建Xendit支付网关AI助手：开发效率提升实战

news 2026/5/13 9:05:23

1. 项目概述：一个为Xendit API量身打造的MCP服务器

最近在对接东南亚支付网关Xendit时，发现了一个挺有意思的开源项目：mrslbt/xendit-mcp。简单来说，这是一个实现了Model Context Protocol (MCP)的服务器，专门用于将Xendit的支付功能无缝集成到支持MCP的AI助手或应用中，比如Claude Desktop、Cursor等。

如果你正在开发涉及东南亚市场的电商、SaaS或者任何需要在线收款的应用，并且希望你的AI开发伙伴能直接帮你处理支付查询、创建发票、甚至发起退款，那么这个项目可能就是你要找的“桥梁”。它本质上是一个适配层，把Xendit那套复杂的REST API，转换成了AI助手能理解并直接操作的标准化“工具”。这样一来，你不需要每次都去翻Xendit的文档写curl命令，直接在AI对话窗口里说一句“帮我查一下订单INV-123的状态”，它就能给你返回结构化的结果。

这个项目的核心价值在于提升开发与运维效率。想象一下，你在调试一个支付回调问题，可以直接问AI助手：“列出过去一小时所有状态为PENDING的虚拟账户交易。”而不需要离开你的编码环境去打开Postman或登录Xendit Dashboard。对于需要频繁与支付系统交互的开发者或运维人员来说，这能节省大量上下文切换的时间。

2. 核心架构与MCP协议解析

2.1 什么是MCP？为什么它重要？

Model Context Protocol (MCP) 是由Anthropic提出的一种开放协议，旨在为大型语言模型（LLM）提供一种标准化的方式来访问外部工具、数据源和计算资源。你可以把它理解为AI世界的“USB协议”或“驱动程序框架”。

在MCP架构中，主要有三个角色：

MCP 客户端 (Client)：通常是AI应用本身，比如Claude Desktop。它负责发起请求。
MCP 服务器 (Server)：比如我们这个xendit-mcp项目。它封装了特定领域（这里是Xendit支付）的所有能力和数据，并将其暴露为一系列“工具(Tools)”和“资源(Resources)”。
传输层 (Transport)：客户端与服务器通信的方式，常见的是stdio（标准输入输出）或SSE。

mrslbt/xendit-mcp扮演的就是MCP服务器的角色。它内部实现了与Xendit API对话的所有逻辑，然后通过MCP协议，向AI客户端宣告：“我这里有以下工具可用：create_invoice,get_invoice,list_virtual_accounts...”。当用户在AI客户端里提出相关需求时，客户端会识别意图，通过MCP调用对应的工具，服务器执行实际的Xendit API调用，并将结果格式化后返回。

2.2 项目技术栈与设计思路

浏览项目代码（通常为TypeScript/Node.js），其设计清晰地遵循了单一职责和模块化原则：

核心依赖：项目基于官方的@modelcontextprotocol/sdk开发，这是构建MCP服务器的SDK。同时，必然依赖xendit-node这个官方SDK来与Xendit API进行安全、高效的通信。
配置驱动：所有Xendit相关的配置，如API密钥、环境（沙盒/生产），都通过环境变量或配置文件注入，保证了安全性和灵活性。
工具封装：每一个Xendit的核心功能都被封装成一个独立的MCP Tool。例如：
- create_invoice：封装了创建支付发票的逻辑，参数映射了Xendit API的必填和选填字段。
- get_payment：封装了根据ID查询支付详情的逻辑。
- create_refund：封装了发起退款的逻辑。
错误处理与日志：良好的MCP服务器会捕获Xendit API调用中的异常（如网络错误、认证失败、参数错误），并将其转换为MCP协议规定的标准错误格式，同时输出结构化日志，便于调试。

注意：使用此类MCP服务器时，务必理解它只是一个“代理”或“转换器”。你的API密钥等敏感信息会存储在运行MCP服务器的环境中（通常是你的本地开发机或受信任的服务器），而不是AI客户端里。安全性取决于你部署MCP服务器本身的环境安全。

3. 从零开始部署与配置实战

3.1 环境准备与依赖安装

假设你已经在本地开发环境（推荐使用VS Code或Cursor，它们对MCP支持良好）中准备好了Node.js（版本18或以上）和npm。

首先，你需要获取项目代码。由于这是一个开源项目，通常你可以直接克隆仓库：

git clone https://github.com/mrslbt/xendit-mcp.git cd xendit-mcp npm install

安装过程会拉取@modelcontextprotocol/sdk和xendit-node等关键依赖。如果项目提供了Dockerfile，你也可以选择使用Docker构建，这对于保证环境一致性非常有利。

3.2 关键配置详解：安全地接入Xendit

配置是连接Xendit的核心，也是最容易出错的地方。你需要在Xendit后台（https://dashboard.xendit.co）获取以下关键信息：

API密钥：这是你的身份凭证。绝对不要将其硬编码在代码中或提交到版本控制系统。
- 沙盒环境密钥：用于测试，通常以xnd_development_开头。
- 生产环境密钥：用于真实交易，通常以xnd_production_开头。
环境选择：明确你当前是测试还是生产。

在项目根目录，你应该会找到一个如.env.example的示例文件。复制它并创建你自己的.env文件：

cp .env.example .env

然后编辑.env文件，填入你的配置：

# Xendit 配置 XENDIT_SECRET_KEY=你的_XENDIT_API_密钥 XENDIT_ENVIRONMENT=sandbox # 或 `production` # MCP 服务器配置（可选） SERVER_PORT=3000 # 如果使用HTTP/SSE传输可能需要 LOG_LEVEL=info

实操心得：即使在开发阶段，也强烈建议先使用沙盒环境的API密钥。沙盒环境模拟了所有支付流程（成功、失败、过期），但不会产生真实资金流动，是安全测试的必备。你可以使用Xendit提供的测试卡号（如4000000000000002）来模拟信用卡支付。

3.3 与AI客户端集成：以Claude Desktop为例

配置好服务器后，下一步是让它被你的AI客户端识别。不同的客户端配置方式不同，这里以目前最流行的Claude Desktop为例。

首先，确保你的xendit-mcp服务器可以正常运行。在项目目录下执行启动命令，通常是：
```
npm start # 或如果配置了脚本 npm run dev
```
如果看到类似“MCP server running on stdio”或“Server started on port 3000”的日志，说明服务器已就绪。
配置Claude Desktop。你需要找到Claude Desktop的配置文件夹。
- macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:%APPDATA%\Claude\claude_desktop_config.json
编辑配置文件。在claude_desktop_config.json中，你需要添加一个mcpServers配置项。由于xendit-mcp通常通过stdio通信，配置可能如下所示：

{ "mcpServers": { "xendit": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/YOUR/xendit-mcp/build/index.js" // 指向你编译后的入口文件 ], "env": { "XENDIT_SECRET_KEY": "你的_沙盒_密钥", "XENDIT_ENVIRONMENT": "sandbox" } } } }

关键点解析：

command: 指定运行服务器的命令，这里是node。
args: 数组，第一个元素是项目入口文件的绝对路径。如果你直接运行TS文件，可能需要ts-node。
env: 这里直接传递环境变量是一种方式，但更安全的做法是在启动MCP服务器的系统环境中设置好.env文件，这里只配置命令。将密钥写在JSON配置中仍有一定风险，需妥善保管该配置文件。

保存配置并重启Claude Desktop。重启后，Claude应该就能连接到你的Xendit MCP服务器了。你可以在Claude的输入框里尝试说：“你有哪些可用的工具？” 或者 “帮我创建一个金额为10000 IDR（印尼盾）的测试发票，外部ID是test_order_001。” 如果配置成功，Claude会识别出create_invoice工具并询问你所需的其他参数（如付款人邮箱）。

4. 核心功能工具详解与调用示例

xendit-mcp项目将Xendit API的多个端点封装成了独立的工具。了解每个工具的用途和参数，是高效利用它的关键。

4.1 发票管理工具集

发票（Invoice）是Xendit最常用的支付方式之一，适用于B2C场景，用户会收到一个包含支付链接的邮件或页面。

工具名：create_invoice
- 功能：创建一张支付发票。
- 核心参数：
  - external_id(字符串):必填。你系统内部的唯一订单号，用于对账。这是最重要的参数，必须保证在你系统内唯一。
  - amount(数字):必填。金额。这里有一个巨坑：Xendit的金额单位是该货币的最小单位。对于印尼盾(IDR)，1 IDR就是1单位。但对于菲律宾比索(PHP)，金额需要乘以100（即100代表1 PHP）。务必查阅Xendit对应支付方式的文档。
  - payer_email(字符串):必填。付款人邮箱，发票链接将发送至此。
  - description(字符串): 可选。订单描述，会显示在发票上。
- AI调用示例：“创建一个金额为50000 IDR的发票，外部ID是order_20240415_001，发给customer@example.com，描述写‘Premium Plan Subscription’。”
- 服务器响应：AI会返回一个包含invoice_url（支付链接）和id（Xendit发票ID）等字段的对象。你需要将这个invoice_url提供给用户完成支付。
工具名：get_invoice
- 功能：根据发票ID查询状态和详情。
- 核心参数：invoice_id(字符串)。
- 使用场景：用户支付后，你需要轮询或通过webhook回调来更新订单状态。在调试时，直接用这个工具查询非常方便。

4.2 直接支付与退款工具

除了发票，Xendit还支持信用卡、便利店、银行转账等多种直接支付方式。

工具名：create_payment(可能根据项目实现命名略有不同，如charge_card)
- 功能：直接发起一笔支付（如信用卡扣款）。
- 核心参数：极其复杂，涉及卡信息token（由前端Xendit.js收集）、金额、货币等。重要提示：PCI DSS合规要求敏感卡数据绝不能经过你的服务器。因此，这个工具通常需要与前端配合使用，前端获取到代表卡的token后，传给后端或AI上下文，再由MCP服务器调用。
- 注意事项：在生产环境使用直接支付工具前，必须在Xendit后台完成严格的合规审核（KYC），否则功能无法启用。
工具名：create_refund
- 功能：对一笔已成功的支付发起退款。
- 核心参数：
  - payment_id(字符串): 需要退款的原始支付ID。
  - amount(数字): 退款金额（同样注意货币单位）。
  - reason(字符串): 退款原因。
- 实操心得：退款操作需要谨慎。部分支付方式（如某些银行的虚拟账户）可能不支持退款，或退款处理时间较长。发起退款前，最好先通过get_payment工具确认支付状态是否为CAPTURED（已捕获/成功）。

4.3 查询与对账工具

这些工具对于运营和财务对账至关重要。

工具名：list_payments或get_transactions
- 功能：根据条件（如时间范围、状态、支付方式）筛选查询交易列表。
- 核心参数：limit,created_after,created_before,status等。
- AI调用示例：“列出今天所有状态为成功的信用卡交易，最多10条。”
- 价值：快速核对当日营收，无需登录Xendit仪表盘。
工具名：get_balance
- 功能：查询你在Xendit账户中的可用余额。
- 使用场景：在发起提现前，或日常财务健康检查时使用。

5. 高级应用：Webhook集成与事件处理

MCP服务器主要用于主动查询和操作，但支付的核心异步通知机制——Webhook——同样重要。虽然xendit-mcp项目本身可能不直接处理Webhook（这通常是你主后端服务的职责），但理解如何与MCP服务器协同工作至关重要。

5.1 Webhook配置与验证

在Xendit后台配置Webhook：进入Dashboard，设置你的Webhook端点URL（例如，https://your-api.com/xendit/webhook）。你需要为不同事件（如invoice.paid,payment.captured）指定同一个或不同的端点。
验证Webhook签名：Xendit发送的每个Webhook请求头中都包含一个x-callback-token字段，它是你预先在后台设置的验证令牌。你的后端服务必须校验这个令牌，以确保请求确实来自Xendit，防止伪造请求。
处理事件：收到已验证的Webhook后，你的后端服务会根据事件类型（如invoice.paid）和事件数据中的external_id，更新你自己数据库中的订单状态。

5.2 与MCP服务器的协同

当你的后端处理完Webhook，更新了内部订单状态后，可能会产生新的需求。例如：

客服人员需要查询某个有争议的订单的详细支付流水。
开发者需要确认退款是否已经处理完成。

此时，客服或开发者可以直接在集成了xendit-mcp的AI客户端中，使用get_invoice或get_payment工具，输入从内部系统看到的Xendit交易ID，立刻获取最新的、第一手的支付状态信息。这实现了从内部系统到外部支付网关的无缝信息穿透，极大地提升了问题排查和客户支持的效率。

6. 安全、监控与最佳实践

6.1 安全注意事项

密钥管理是第一生命线：
- 永远不要将生产环境的API密钥提交到Git仓库，即使私有仓库也有风险。
- 使用.env文件并加入.gitignore。
- 在生产服务器上，使用安全的密钥管理服务（如AWS Secrets Manager, HashiCorp Vault）或环境变量。
- 为MCP服务器使用的API密钥设置最小必要权限（如果Xendit支持）。
控制MCP服务器的访问：
- 本地的Claude Desktop使用是相对安全的。
- 如果你将MCP服务器部署到网络环境中供团队使用，必须为其配置严格的网络访问控制（防火墙规则）和认证机制（例如，让MCP服务器监听本地端口，并通过SSH隧道或反向代理配合API密钥访问）。
审计日志：
- 确保MCP服务器记录了所有工具调用的日志，包括谁（通过上下文推断）、在什么时候、调用了什么工具、输入参数是什么（敏感参数如卡token需脱敏）、结果如何。这对于问题回溯和安全审计至关重要。

6.2 性能与监控

速率限制：Xendit API有严格的速率限制。你的MCP服务器应该实现简单的请求队列或缓存机制，避免在AI客户端被频繁询问时，对Xendit API发起洪水攻击。
健康检查：为MCP服务器添加一个简单的健康检查端点或机制，确保它长期运行稳定。
错误告警：监控MCP服务器的日志，对频繁出现的认证错误、API限额错误等设置告警，这可能是密钥泄露或业务量突增的信号。

6.3 开发与调试技巧

使用MCP Inspector：Anthropic提供了一个名为mcp-inspector的调试工具。你可以用它来独立测试你的MCP服务器，查看它宣告了哪些工具和资源，并手动调用它们，而无需依赖Claude Desktop。这对于开发阶段排查问题非常有用。
```
npx @modelcontextprotocol/inspector node ./build/index.js
```
模拟响应：在开发测试时，可以考虑修改MCP服务器代码，在沙盒环境下对特定请求返回模拟数据，避免频繁调用真实的沙盒API（虽然沙盒无成本，但可能有速率限制）。
参数验证：在MCP工具的实现内部，在调用Xendit SDK之前，先对输入参数进行严格的验证和格式化（例如，确保金额是正确的数字类型和单位），返回清晰的自定义错误信息，这比让Xendit API返回一个晦涩的错误再传递给AI客户端要友好得多。

7. 常见问题与故障排除实录

在实际集成和使用中，你肯定会遇到各种问题。下面是我遇到的一些典型情况及其解决方法。

7.1 连接与配置问题

问题：Claude Desktop重启后，提示无法连接到MCP服务器或工具列表为空。
- 排查步骤：
  1. 检查MCP服务器进程是否在运行。在终端执行ps aux | grep xendit-mcp(Linux/macOS) 或查看任务管理器。
  2. 检查Claude Desktop配置文件的路径和格式是否正确。JSON格式非常严格，一个多余的逗号就会导致解析失败。
  3. 查看MCP服务器的启动日志。通常权限问题、Node.js版本不兼容、依赖缺失都会在启动时报错。确保你是用正确的路径和命令启动的。
- 解决：最常见的错误是配置文件中args里的路径不正确。使用绝对路径最保险。另外，尝试在终端手动运行配置中的命令，看是否能启动成功。
问题：调用工具时，返回“Authentication failed”或“Invalid API key”。
- 排查：
  1. 确认.env文件中的XENDIT_SECRET_KEY是否正确，前后有无空格。
  2. 确认XENDIT_ENVIRONMENT是否与密钥类型匹配（沙盒密钥配sandbox）。
  3. 在服务器代码中打印出加载的环境变量值（仅限开发环境），确认是否被正确读取。
- 解决：重新从Xendit Dashboard复制密钥。沙盒和生产环境的密钥完全不同，切勿混用。

7.2 API调用与业务逻辑问题

问题：创建发票成功，但用户收不到邮件。
- 排查：
  1. 首先用get_invoice工具查询该发票，确认payer_email字段是否填写正确。
  2. 在Xendit Dashboard的“Notifications”或发票详情页，查看邮件发送日志。有时邮件可能被归入垃圾邮件。
  3. 检查发票状态是否为PENDING。已过期(EXPIRED)或已支付(PAID)的发票不会重复发送邮件。
- 解决：确保邮箱地址有效。对于测试，可以使用真实的邮箱或临时邮箱服务。Xendit沙盒环境可能不会真实发送邮件，但生产环境一般很可靠。
问题：调用create_payment（信用卡支付）失败，提示“Token is invalid or expired”。
- 排查：
  1. 这个token是由前端Xendit.js库生成的单次使用令牌，有效期很短（通常几分钟）。
  2. 检查从前端获取token到后端/MCP服务器发起支付请求的间隔是否过长。
  3. 确认前端集成Xendit.js的代码正确，特别是public key是否正确（沙盒和生产环境也不同）。
- 解决：优化前端到后端的通信流程，获取token后立即发起支付请求。在测试时，模拟一个快速的端到端流程。
问题：查询交易列表时，返回的数据量不对或缺少预期交易。
- 排查：
  1. Xendit API的列表接口通常是分页的。检查你是否处理了has_more字段和after_id参数来获取所有数据。
  2. 确认你使用的查询参数（如created_after）的时区。Xendit API通常使用UTC时间。
  3. 支付方式筛选：你是否指定了payment_method？不同的支付方式（如信用卡、虚拟账户）可能在不同的接口中查询。
- 解决：仔细阅读Xendit官方API文档中关于分页和过滤参数的说明。在MCP服务器工具实现中，可以考虑内置一个逻辑，自动循环获取直到拿到所有分页数据，再返回给AI客户端，但这要注意性能。

7.3 性能与稳定性问题

问题：AI客户端调用工具响应缓慢。
- 排查：
  1. 网络问题：你的MCP服务器部署在哪里？如果和Xendit API服务器网络延迟高，会影响速度。
  2. MCP服务器性能：检查服务器运行主机的CPU/内存使用情况。如果工具逻辑复杂或未做缓存，可能成为瓶颈。
  3. Xendit API限流：频繁调用可能触发限流，导致请求延迟或失败。
- 解决：对于查询类工具（如get_balance,get_invoice），可以在MCP服务器端实现一个简单的内存缓存（例如，缓存5分钟），减少对Xendit API的直接调用。同时，确保你的服务器部署在低延迟的区域。

将mrslbt/xendit-mcp这样的MCP服务器集成到你的开发流中，初期需要一些配置和调试成本，但一旦跑通，它带来的效率提升是显著的。它尤其适合那些需要频繁与支付系统交互进行查询、对账、问题排查的角色，比如开发人员、运维工程师、甚至财务支持人员。它把复杂的API交互变成了自然的对话，让开发者能更专注于业务逻辑本身，而不是记忆繁琐的API参数和格式。

查看全文

http://www.jsqmd.com/news/807763/