MCP 服务器

@paymos/mcp 把沙箱账单工具和开发文档接入编程客户端。服务器在本机通过 stdio 通信，不开放监听端口。智能体可以调用工具测试集成，正式环境仍由你的应用使用服务器 SDK。

前置条件

准备 Node.js 20 或更新版本，以及一对测试 API 密钥：pk_test_ 密钥 ID 和 sk_test_ 密钥。

连接客户端

终端中运行：

npx -y @paymos/mcp setup

按提示选择客户端，再输入测试密钥。密钥输入不会回显。需要校验 webhook 签名时，再填写 webhook 密钥。也可以直接指定客户端：

npx -y @paymos/mcp setup --client codex
npx -y @paymos/mcp setup --client kimi
npx -y @paymos/mcp setup --client opencode

--client 接受 codex、claude-code、claude-desktop、kimi、cursor、windsurf、opencode、vscode 和 generic。Cline、Roo Code 或自定义客户端可选 generic，但必须指定 --config。先从客户端的 MCP 设置中找到实际文件路径：

npx -y @paymos/mcp setup --client generic --config /path/to/mcp.json

Kimi CLI 默认写入 ~/.kimi-code/mcp.json；设置了 KIMI_CODE_HOME 时，写入该目录的 mcp.json。其他位置可用 --config PATH 指定。--credentials-file PATH 则指定密钥文件，两个路径用途不同。

密钥单独保存在 ~/.config/paymos/mcp/credentials.json。设置了 XDG_CONFIG_HOME 时，改用该目录下的 paymos/mcp/credentials.json。客户端配置只保存 PAYMOS_CREDENTIALS_FILE 路径，密钥文件不要提交到代码仓库。自动化脚本可预先设置 PAYMOS_API_KEY_ID、PAYMOS_API_SECRET，以及可选的 PAYMOS_WEBHOOK_SECRET。没有交互终端且参数不全时，命令会报错退出。

想先检查写入计划，添加 --dry-run。它不会修改文件，也不会显示密钥。完整参数见 --help。原有 MCP 服务器、注释和模型设置都会保留；相同密钥重复配置不会增加条目。若已有 Paymos 配置冲突，或密钥文件存着另一对密钥，命令会拒绝覆盖。先核对报错中的目标路径，再决定用哪个配置文件。完成后重启客户端，或重新连接 MCP。

接上了，模型却不调用工具？

先看客户端能否列出 paymos 工具。连接失败时，检查 Node.js 版本、npx 是否可用，以及密钥文件路径。能看到工具却没有调用，则检查模型是否支持工具调用，以及客户端是否开启了这项功能。

Codex、Kimi CLI、OpenCode 都由客户端管理 MCP。GLM 或自定义模型同样需要支持工具调用。用 Claude Code 连接 GLM 时，MCP 仍配置在 Claude Code 中。setup 不会更换模型或模型 API 端点，也不代表所有模型都能调用这些工具。

需要手动配置时

先建立独立密钥文件，webhookSecret 可省略：

{"apiKeyId":"pk_test_…","apiSecret":"sk_test_…","webhookSecret":"whsec_…"}

Unix 上，创建文件后限制读取权限。若组或其他用户能读取文件，服务器会拒绝加载：

chmod 600 /absolute/path/credentials.json

Windows 沿用用户目录现有的 ACL 权限。

通用客户端

使用 mcpServers 格式的客户端可加入以下配置。将示例路径换成密钥文件的绝对路径：

{
  "mcpServers": {
    "paymos": {
      "command": "npx",
      "args": ["-y", "@paymos/mcp"],
      "env": {"PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json"}
    }
  }
}

Codex

Codex 使用 ~/.codex/config.toml；若设置了 CODEX_HOME，则使用该目录的 config.toml：

[mcp_servers.paymos]
command = "npx"
args = ["-y", "@paymos/mcp"]

[mcp_servers.paymos.env]
PAYMOS_CREDENTIALS_FILE = "/absolute/path/credentials.json"

OpenCode

OpenCode 使用 mcp，本地命令写成数组：

{
  "mcp": {
    "paymos": {
      "type": "local",
      "command": ["npx", "-y", "@paymos/mcp"],
      "environment": {"PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json"},
      "enabled": true
    }
  }
}

VS Code

VS Code 的 .vscode/mcp.json 使用顶层 servers，并在 paymos 条目中加入 "type": "stdio"。

Zed

Zed 需手动接入，按 context_servers 格式填写。Unix 全局配置为 ~/.config/zed/settings.json，项目配置为 .zed/settings.json。Windows 请从 Zed 设置中打开实际使用的 settings.json。

Windows 启动命令

Windows 使用 "command": "cmd"，参数改为 ["/d", "/c", "npx", "-y", "@paymos/mcp"]。密钥文件路径仍放在环境变量中。

旧环境变量和 --api-key-id、--api-secret 参数仍有效；读取顺序为环境变量、命令行参数、密钥文件。

六个工具与五份文档

工具	用途
create_invoice	创建沙箱账单；按 external_order_id 幂等，返回 payment_url
get_invoice	读取账单状态
list_invoices	按条件筛选，以游标分页
cancel_invoice	取消未支付账单并记录原因
simulate_invoice_payment	模拟 paid、overpaid、underpay、cancel、paid_late
verify_webhook_signature	在本地校验 X-Webhook-Signature

文档资源包括 paymos://docs/quick-start、paymos://docs/hosted-checkout、paymos://docs/webhooks、paymos://docs/testing-sandbox、paymos://docs/server-sdks，可在会话内读取。

测试范围

服务器只接受测试密钥，拒绝正式密钥和转出密钥。模拟支付不会让 MCP 获得正式环境权限。托管 MCP 已延后到第二阶段，目前不可用，也没有发布时间表。

下一步

继续查看沙箱测试、webhook或快速开始。