> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 商户 MCP

> 商户 MCP 面向商户侧客户端，可将自然语言指令转为 GatePay API 调用，完成余额、订单与退款等操作。

## 概述

Model Context Protocol（MCP）是一种开放协议，用于在客户端与外部数据源、工具之间传递上下文。商户 MCP 实现了该协议，充当客户端与 GatePay API 之间的桥梁。当用户输入自然语言指令时，商户 MCP 会将其转换为对应的 GatePay API 调用并返回结果。

<div className="gatepay-facilitator-notice-card">
  <Card title="商户 MCP 支持通过标准 MCP 客户端接入，可用于将自然语言请求映射为 GatePay API 调用。" />
</div>

## 工作原理

1. 用户在客户端中发出指令，例如「查询我的 USDT 余额」
2. 客户端识别意图，调用商户 MCP 暴露的 `balances_get` 工具
3. 商户 MCP 使用商户受限 API Key 向 GatePay API 发起签名请求
4. GatePay 返回结果，由商户 MCP 将结构化数据交回客户端
5. 客户端以自然语言向用户呈现查询结果

## 安装与配置

### 前置条件

1. 完成 GatePay 商户入驻
2. 已创建应用并获取支付秘钥、ClientId 与受限 API Key（Restricted API Key）

### 客户端配置

将以下 JSON 配置添加到你的 MCP 客户端设置中，把 `GATEPAY_CLIENT_ID`、`GATEPAY_SECRET_KEY` 和 `GATEPAY_RESTRICTED_KEY` 替换为真实凭证后保存，并重启或重载客户端。以下示例适用于支持标准 MCP 配置格式的客户端。

```json theme={null}
{
  "mcpServers": {
    "gatepay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "payment-mcp"],
      "env": {
        "GATEPAY_CLIENT_ID": "CLIENT_ID",
        "GATEPAY_SECRET_KEY": "SECRET_KEY",
        "GATEPAY_RESTRICTED_KEY": "RESTRICTED_KEY",
        "GATEPAY_BASE_URL": "https://openplatform.gateapi.io/payment/open/api/mcp"
      }
    }
  }
}
```

<div className="gatepay-github-card">
  <Card icon="https://mintcdn.com/gateglobalcorp/-BUf7BZGLTCh5iYe/icon/github.svg?fit=max&auto=format&n=-BUf7BZGLTCh5iYe&q=85&s=846d0112b821219571bdcbee940d2d07" title="源码与更多说明" href="https://github.com/gate/gatepay-merchant-mcp" width="64" height="64" data-path="icon/github.svg" />
</div>

### 受限 API Key 生成

为确保安全性，建议为商户 MCP 创建受限 API Key（Restricted API Key），并仅授予所需的最小权限。

1. 登录 <a href="https://www.gate.com/zh/pay-merchant" style={{ color: '#16A34A' }}>GatePay商户后台</a>，进入开发者中心 - 应用配置页面
2. 创建支付秘钥和支付应用，并提交上线申请
3. 创建受限 API Key，根据实际使用的 MCP 工具勾选所需权限
4. 保存已生成的支付秘钥、ClientId 与受限 API Key

## 支持的工具列表

商户 MCP 提供以下工具，客户端可通过 MCP 协议直接调用。更多工具将持续上线。

<div className="two-column-table">
  | 功能                      | 名称                     |
  | ----------------------- | ---------------------- |
  | 提现订单状态查询                | withdrawQuery          |
  | 根据退款id查询退款详情            | v2PayRefundDetails     |
  | 查询法币与加密货币之间的实时汇率        | rateQuery              |
  | 查询商户可用余额                | v1Balance              |
  | 根据订单id查询订单详情            | v2QueryOrder           |
  | 发起标准订单退款                | v2StandardOrderRefund  |
  | 根据提供的币种，查询支持接受此币种的所有可用链 | v1PayAddressChains     |
  | 查询Gate地址支付支持的所有币种列表     | v1PayAddressCurrencies |
  | 创建固定收款码                 | fixedAddressCreate     |
  | 创建收款链接                  | payCode                |
</div>

## 常见问题

### 商户 MCP 支持哪些客户端？

任意支持 MCP 的客户端均可按本文「客户端配置」添加 `mcpServers` 片段。

### 商户 MCP 是否会缓存 API 响应？

不会。每次 Tool 调用都会实时向 GatePay API 发起请求，确保数据的实时性和准确性。

### 如何确保 API Key 安全？

建议采取以下措施：

1. 使用受限 API Key，仅授予最小权限
2. 通过环境变量传递密钥，避免硬编码在配置文件中
3. 在生产环境使用远程托管模式，密钥由服务端管理

### 工具调用失败如何排查？

常见排查步骤：

1. 检查 API Key 和 Secret 是否正确配置
2. 确认受限 API Key 具有对应工具所需的权限
3. 检查网络连接是否正常
4. 查看商户 MCP 日志输出，确认错误码

### 是否支持批量操作？

当前工具主要面向单次请求场景。对于批量工作流，建议由客户端或业务系统在应用层编排多次调用并聚合结果。