注册上游 MCP Server
什么时候用
需要接入自定义工具能力时，通过注册上游 MCP Server 来聚合第三方服务的工具（如 CRM、知识库、文件系统等），让 Agent 可以调用这些工具完成任务。
你需要准备
- 上游 MCP Server 的接入地址
- 认证信息（取决于上游服务要求）
- 明确该 Server 的使用环境（开发/预发/生产）
操作步骤
第 1 步：进入 MCP Server 管理
左侧菜单 → MCP 网关 → MCP Server 管理。
页面以列表展示你已注册的 Server。点击右上角「新增 Server」按钮，进入创建表单。
第 2 步：填写 Server 信息
表单包含以下字段：
| 字段 | 怎么填 | 说明 |
|---|---|---|
| 显示名称 | 必填，如「CRM 生产环境」 | 控制台展示用 |
| 标识 | 必填，如 crm_prod | 内唯一；工具名前缀会使用该标识 |
| 描述 | 可选，如「对接公司 CRM 系统，提供客户查询功能」 | 描述用途 |
| 接入地址 | 必填，如 https://crm.example.com/mcp | 上游 MCP Server 的 Streamable HTTP URL |
| 环境 | 必选，开发/预发/生产 | 用于区分不同环境的 Server |
| 认证方式 | 必选，无认证/Bearer Token/Basic 认证/自定义 Header | 选择上游 Server 要求的认证方式 |
| 认证凭证 | 可选（取决于认证方式） | 输入对应凭证；编辑时留空表示保持原有凭证不变 |
| 官方服务 | 可选（仅平台管理员可见） | 标记为平台官方服务 |
| 启用 | 可选，默认开启 | 关闭后该 Server 提供的工具不可用 |
标识规则：只能包含大小写字母、数字、下划线和中横线，且不能包含连续双下划线。
第 3 步：测试连接
填写完接入地址和认证信息后，点击「测试连接」按钮。
- 连接成功：显示「✅ 连接成功，发现 N 个工具」
- 连接失败：显示「❌ 连接失败」，请检查地址和认证凭证是否正确
启用前必须先测试连接成功。
第 4 步：保存
确认连接测试通过后，点击「保存」。成功后自动返回列表页，新 Server 出现在列表中。
第 5 步：刷新工具（可选）
创建成功后，系统会自动尝试同步工具。如需手动刷新，在列表页点击该 Server 操作列的「刷新工具」按钮。
刷新成功会显示：「刷新成功（新增 N，更新 N，移除 N，合计 N）」。
怎么验证成功了
- 回到 MCP Server 列表，能看到刚创建的 Server
- 工具数列显示该 Server 提供的工具数量（大于 0 表示同步成功）
- 点击「刷新工具」能正常执行并返回结果
- 在「同步工具与查看权限」页面能看到该 Server 的工具绑定情况
常见问题
保存时提示「标识已存在」
标识在内必须唯一。请更换一个不同的标识。
连接测试失败
- 检查接入地址是否正确，确保是完整的 URL（包含
https://或http://） - 确认认证方式和凭证是否正确
- 检查上游服务是否正常运行
- 确认网络是否允许访问该地址
认证凭证怎么更新
编辑 Server 时，若需更换凭证，直接在「认证凭证」字段输入新值并保存；若保持原有凭证不变，留空该字段即可。
工具数一直是 0
- 先点击「刷新工具」尝试手动同步
- 若仍为 0，检查上游服务是否正常提供工具
- 查看调用日志确认是否有错误
官方服务标记有什么用
标记为官方的 Server 会有特殊标识，通常用于平台提供的内置服务。仅平台管理员可设置。
深入
核心概念
MCP Server
MCP Server 是租户注册的上游服务。
核心字段：
- name：租户内唯一，也参与工具名前缀
- endpoint：上游 Streamable HTTP URL
- auth_type：none / bearer / basic / custom
- auth_credentials：写入时明文，后端加密
- is_enabled：人工开关
- server_status：健康状态
is_enabled vs server_status
| 字段 | 谁控制 | 含义 |
|---|---|---|
| is_enabled | 租户管理员 | 是否人工启用 |
| server_status | 健康检查或平台维护 | active / inactive / error |
运行时可用通常要求两者都满足。
工具命名
Gateway 暴露工具名格式：{server_name}__{tool_name}。
例：crm__search_customer。
工具元数据缓存
管理端工具列表来自 mcp_tool 表。
缓存特点：
- 仅用于 Admin UI 工具发现
- Pipeline 运行时仍走 Gateway 实时
- (mcp_server_id, name) 唯一
- 删除 Server 会级联删除 Tool 缓存
同步触发点：
| 触发点 | 行为 |
|---|---|
| 注册 Server 后 | best-effort 后台同步，失败不阻断 |
| 手动刷新 | 短连接上游并 upsert 缓存 |
权限边界
| 操作 | 租户 admin | 平台管理员 |
|---|---|---|
| 创建本租户 Server | 可以 | 可以 |
| 查看本租户 Server | 可以 | 可以 |
| 更新本租户 Server | 可以 | 可以 |
| 删除本租户 Server | 可以 | 可以 |
| 设置 is_official=true | 不可以 | 可以 |
| 查看本租户工具缓存 | 可以 | 可以 |
| 刷新本租户工具缓存 | 可以 | 可以 |
| 查看本租户调用日志 | 可以 | 可以 |
| 查看其它租户资源 | 不可以 | 可按平台权限处理 |
常见坑
- 工具缓存不等于运行时实时工具；Pipeline 仍走 Gateway 实时
- 创建 Server 成功但工具数为 0，通常是 best-effort 同步失败
- is_enabled=true 但 server_status 不是 active 时仍可能不可用
- 同 Server 并发刷新或触发限流会返回错误
- 删除 Server 会级联删除工具缓存
排错速查
| 症状 | 可能原因 |
|---|---|
| tools/list 为空 | 没有 active Server |
| 工具缓存为空 | 未同步或同步失败 |
| 刷新返回错误 | 上游不可达或凭证错 |
| 刷新返回错误 | 并发刷新或限流 |
| 创建返回错误 | name 重复 |
| 日志为 denied | Server 不存在或不可用 |