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

# MCP 集成指南

> 通过模型上下文协议（MCP），让 AI 助手直接查询 UQPAY API 文档。

UQPAY 开发者文档站支持 [模型上下文协议（MCP）](https://modelcontextprotocol.io/introduction)，这是一项开放标准，允许 AI 助手直接访问外部数据源。将你的 AI 编码工具接入 UQPAY MCP 服务后，无需离开开发环境即可搜索和读取文档内容。

## 使用 MCP 能做什么

接入之后，你的 AI 助手可以：

* 在所有 UQPAY 文档中搜索指南、API 参考和代码示例
* 获取任意文档页的完整内容
* 基于最新文档回答关于 UQPAY 产品、API 和集成模式的问题

## 前置条件

* 一个 UQPAY 沙盒或生产账户
* 一款支持 MCP 的 AI 工具，例如：
  * [Claude Desktop](https://claude.ai/download)
  * [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)
  * [Cursor](https://www.cursor.com/)
  * [Windsurf](https://windsurf.com/)
  * [VS Code with Copilot](https://code.visualstudio.com/)

## 接入

UQPAY MCP 服务端点：

```
https://developers.uqpay.com/mcp
```

<Tabs>
  <Tab title="Claude Desktop">
    打开 Claude Desktop 配置文件：

    * **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`

    在 `mcpServers` 对象中加入以下内容：

    ```json theme={null}
    {
      "mcpServers": {
        "uqpay-docs": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://developers.uqpay.com/mcp"
          ]
        }
      }
    }
    ```

    重启 Claude Desktop 使配置生效。
  </Tab>

  <Tab title="Claude Code">
    在终端运行：

    ```bash theme={null}
    claude mcp add uqpay-docs -- npx -y mcp-remote https://developers.uqpay.com/mcp
    ```
  </Tab>

  <Tab title="Cursor">
    打开 Cursor 设置，进入 MCP 区域，添加一个新的 MCP 服务：

    * **Name**：`uqpay-docs`
    * **Type**：`command`
    * **Command**：`npx -y mcp-remote https://developers.uqpay.com/mcp`

    或者在项目的 `.cursor/mcp.json` 中加入：

    ```json theme={null}
    {
      "mcpServers": {
        "uqpay-docs": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://developers.uqpay.com/mcp"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    打开 Windsurf 设置，进入 Cascade > MCP，添加一个新服务：

    ```json theme={null}
    {
      "mcpServers": {
        "uqpay-docs": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://developers.uqpay.com/mcp"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code (Copilot)">
    在 VS Code `settings.json` 或项目级 `.vscode/mcp.json` 中加入：

    ```json theme={null}
    {
      "mcp": {
        "servers": {
          "uqpay-docs": {
            "command": "npx",
            "args": [
              "-y",
              "mcp-remote",
              "https://developers.uqpay.com/mcp"
            ]
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 可用工具

MCP 服务提供两个工具：

| 工具                              | 说明                                         |
| ------------------------------- | ------------------------------------------ |
| `search_uqpay_developer_docs`   | 在文档中搜索相关指南、API 参考和代码示例，返回带页面标题和直达链接的上下文片段。 |
| `get_page_uqpay_developer_docs` | 按路径读取某一页面的完整内容。当你需要完整详情而不仅是搜索片段时使用。        |

典型流程：先用 **search** 找到目标页面，再用 **get\_page** 获取完整内容。

## 示例 Prompt

接入成功后，可以在 AI 助手中试试这些 Prompt：

| Prompt                                 | 作用                  |
| -------------------------------------- | ------------------- |
| "如何用 UQPAY Global Account API 创建一笔出款？" | 搜索出款指南并返回分步说明       |
| "展示卡交易事件的 webhook 通知体。"                | 查找并读取卡交易 webhook 文档 |
| "创建虚拟卡需要哪些参数？"                         | 查找建卡 API 参考         |
| "列出所有支持跨币种出款的币种。"                      | 读取支持币种对参考           |
| "如何为支付开启 3DS 验证？"                      | 查找 3DS 集成指南         |

## llms.txt

如果你的 AI 工具不支持 MCP，可以使用 [llms.txt](https://llmstxt.org/) 索引将 UQPAY 文档作为上下文喂给模型。索引地址：

```
https://developers.uqpay.com/llms.txt
```

该文件遵循 `llms.txt` 标准，列出所有可用文档页面及其描述。你可以将它直接交给任何基于 LLM 的工具，帮助它发现并读取 UQPAY 文档。

## 排障

<Accordion title="MCP 服务连不上">
  确认本机已安装 [Node.js](https://nodejs.org/)（v18 或更高），因为 `npx` 是 MCP 桥接的必备工具。执行 `node --version` 检查版本。
</Accordion>

<Accordion title="AI 助手中看不到工具">
  添加 MCP 配置后，**完全重启** AI 工具。有些工具只重新加载不够，需要整体退出再打开。
</Accordion>

<Accordion title="搜索没有结果">
  换不同关键词重新提问。搜索对具体词汇（比如产品名 Card Issuance、Global Account，功能名 payout、webhook，或 API 操作名）效果最好。
</Accordion>