# MCPCat MCP 接入说明（供 AI Agent 读取执行）

> 这份文档供 AI Agent 读取并执行，帮助用户把 MCPCat 接入到其 AI 客户端。
> MCPCat 遵循 MCP 标准，任何支持 MCP 的客户端都可接入；本文档只定义「接入什么」，
> 客户端配置文件的位置与格式由你（Agent）按该客户端的官方文档确定。

## 标准连接参数

| 项 | 值 |
|----|----|
| 端点 URL | 以用户指令中给出的为准（生产环境为 `https://mcp.mcpcat.cn/v1/mcp`） |
| 传输协议 | `streamable-http`（MCP Streamable HTTP） |
| 认证 | HTTP Header `Authorization: Bearer <MCPCAT_API_KEY>` |

等价的通用 JSON 形态（仅作参考，写入时翻译成该客户端要求的格式）：

```json
{
  "mcpServers": {
    "mcpcat": {
      "type": "streamable-http",
      "url": "<MCPCAT_ENDPOINT>",
      "headers": { "Authorization": "Bearer <MCPCAT_API_KEY>" }
    }
  }
}
```

**API Key**：用户在 https://mcpcat.cn/console/keys 创建，明文只在创建时显示一次；若用户未提供，向其询问，并提醒 Key 是私密凭证，不得写入公开仓库、日志、截图或除配置文件外的其他文件。

## Agent 任务流

1. **识别客户端**：判断用户正在使用的 AI 客户端（可参考运行环境、已装软件，或直接询问用户）。
2. **确定配置方式**：依据你的可靠知识或该客户端官方文档的 MCP 配置说明，确认配置文件路径与格式；不确定时先搜索官方文档，仍无法确定就如实告知用户——不要凭猜测写入错误路径。
3. **确认 Key**：见上节「API Key」。
4. **写入配置**：把标准连接参数翻译成该客户端的配置格式写入。要求：
   - **合并写入**：已有其他 MCP 服务器时保留它们，只新增 `mcpcat` 一项，禁止覆盖已有配置；
   - **字段名差异**：部分客户端把 `type` 写作 `transport`/`protocol`、`headers` 写作 `customHeaders`，含义不变；
   - **旧客户端**：仅支持 SSE 的把 `type` 改为 `sse` 尝试；不支持自定义 Header 的无法安全接入，如实告知并建议换用支持的客户端。
5. **验证连通**：用下节 curl 命令（或直接触发 tools/list）确认返回工具列表。
6. **汇报结果**：告诉用户接入了哪个客户端、修改了哪个文件、如何自行验证与更换工具；提醒用户重启或刷新客户端让配置生效。

## 配置验证

```bash
curl -X POST <MCPCAT_ENDPOINT> \
  -H "Authorization: Bearer <MCPCAT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

返回工具列表 JSON 即接入成功。