# MCP 服务器

> 连接本地 Paymos MCP 服务器，将测试密钥存入独立文件，在沙箱中创建账单、模拟支付并验证 webhook。

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

## 前置条件

准备 Node.js 20 或更新版本，以及一对[测试 API 密钥](/zh-hans/docs/api-keys.md)：`pk_test_` 密钥 ID 和 `sk_test_` 密钥。

## 连接客户端

终端中运行：

```sh
npx -y @paymos/mcp setup
```

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

```sh
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 设置中找到实际文件路径：

```sh
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` 可省略：

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

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

```sh
chmod 600 /absolute/path/credentials.json
```

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

### 通用客户端

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

```json
{
  "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`：

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

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

### OpenCode

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

```json
{
  "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 已延后到第二阶段，目前不可用，也没有发布时间表。

## 下一步

继续查看[沙箱测试](/zh-hans/docs/testing.md)、[webhook](/zh-hans/docs/webhooks.md)或[快速开始](/zh-hans/docs/quick-start.md)。