MCP 管理

MCP 管理用于登记外部 MCP 服务，把服务端提供的工具同步到平台，再交给 Agent 或 AgentLite 调用。

MCP 服务负责连接信息，包括服务 URL、认证、请求头和超时；工具的名称、说明和输入参数由 MCP 服务端提供。平台侧通过 更新 获取工具，不需要像普通 HTTP 插件一样逐项定义工具接口。

一、什么时候使用 MCP

对方已经提供 MCP 服务端点，并希望平台直接获取其工具时，使用 MCP 管理。只有普通 HTTP API 时，应使用插件管理；需要在平台内编排固定处理过程时，应使用工作流管理。

两者的核心区别是：

接入方式	工具从哪里来
插件	在平台中配置，或通过 OpenAPI 导入
MCP	由 MCP 服务端定义，平台更新后获取

二、接入前准备

添加服务前，应从 MCP 服务提供方取得：

必要信息	用途
服务端点 URL	建立 MCP 服务连接
认证要求	判断是否使用动态客户端注册，或填写客户端 ID 和密钥
额外请求头	按服务端要求携带固定 Token 或其他 Header
服务用途与工具清单	接入后核对工具是否同步完整
测试账号与测试数据	调试真实工具调用，避免影响生产数据

还应确认平台所在网络能够访问该服务地址。地址、凭证和请求头正确，但网络不可达时，服务同样无法连接。

工具调试会发起真实调用。涉及生成、写入、修改或删除外部数据的工具，应使用测试环境和测试数据。

三、理解服务与工具

例如，将一个图像生成 MCP 服务接入平台：

服务名称：图像生成服务
服务 URL：<服务提供方给出的 MCP 端点>
服务器标识：image-generation
工具：由服务端提供，平台更新后获取

接入后：

• 服务卡片展示服务状态、引用次数和工具数量；
• 服务详情展示连接属性和工具列表；
• 点击 更新 从服务端重新获取工具；
• 应用引用的是服务中的具体工具；
• 工具说明或参数有问题时，需要先由 MCP 服务端修正，再回到平台更新工具。

四、进入 MCP 管理

进入 基础服务 › 组件中心 › MCP 管理。

左侧分组用于管理和筛选服务，右侧可以按服务类型筛选或按名称搜索。服务卡片上的关键信息包括：

信息	重点用途
组件 ID	服务的唯一组件标识，可复制用于核对和定位
引用次数	服务被使用的累计次数，仅供参考，不代表当前实时使用情况
包含工具	核对当前同步到平台的工具数量
服务状态	查看当前健康状态
服务详情	查看连接属性、更新和调试工具

点击左侧 MCP 管理 旁的 ＋ 可创建分组。没有明确归属的服务可放入默认分组。

五、添加 MCP 服务

点击右上角 添加服务。

5.1 填写基础信息

字段	配置要点
服务图标	可选；建议 240px × 240px，不超过 2 MB，支持 JPG、PNG
所属分组	选择便于团队维护和检索的分组
服务名称	使用能够直接识别用途的名称
服务类型	根据服务用途选择业务服务或通用服务
服务 URL	填写服务提供方给出的 MCP 服务端点 URL
服务器标识	工作空间内唯一，只能使用小写字母、数字、下划线和连字符
服务器描述	写明服务用途、主要工具和使用限制

服务器标识建议保持简短、稳定，例如：

image-generation
hospital-query

服务描述主要帮助管理人员识别服务，可以按下面的结构编写：

提供图像生成工具，用于测试环境中的文生图任务。
生成内容不得包含患者身份信息，正式使用前需检查输出结果。

5.2 配置认证

打开 认证 页签。

根据服务提供方给出的接入要求选择：

• 服务方明确要求使用动态客户端注册：开启 使用动态客户端注册；
• 服务方提供了固定客户端凭证：关闭动态客户端注册，填写 客户端 ID 和 客户端密钥；
• 凭证失效或授权信息发生变化：保存服务后可通过 重新授权 再次执行授权。

客户端密钥属于敏感信息，不要写入服务名称、描述、截图或调试数据。

5.3 配置额外请求头

服务端要求携带额外 HTTP Header 时，打开 请求头 页签，以“名称 / 值”的形式添加。

例如服务方要求固定 Token 时，可能提供类似下面的配置要求：

名称：Authorization
值：Bearer <服务方提供的 Token>

请求头的名称和值必须严格按照服务方要求填写。不要在截图、描述或文档示例中保留真实 Token；凭证变化后，应重新验证服务连接和工具调用。

5.4 配置超时

打开 配置 页签。

字段	默认值	作用
超时时间	30 秒	工具调用在 30 秒内没有完成时，本次调用按超时失败处理。普通查询、计算等工具主要受此项影响
SSE 读取超时时间	300 秒	SSE 连接建立后，持续 300 秒没有读到新数据时中断读取。生成时间较长或持续返回数据的工具主要受此项影响

首次接入先使用默认值。若工具总是在接近固定时长后超时，但服务端最终能够正常完成，再根据实测耗时适当增加对应配置；若请求立即失败、始终无响应或耗时波动很大，应先检查地址、认证、网络和服务端状态。

完成三个页签的配置后点击 确定，生成服务卡片。

六、检查服务并更新工具

点击服务卡片底部的 服务详情。

详情抽屉中可以核对：

• 服务器标识、类型和服务 URL；
• 鉴权是否已经配置；
• 普通超时与 SSE 超时；
• 健康状态；
• 服务端提供的工具列表。

健康状态显示 正常，说明当前服务连接处于正常状态，但不代表每个工具都已满足业务要求。工具仍需单独调试。

点击工具列表右上角 更新，从 MCP 服务端刷新工具。以下情况必须更新：

• 服务刚接入，需要确认工具列表；
• 服务端新增、删除或修改了工具；
• 工具名称、说明或参数发生变化；
• 重新授权或修改连接配置后，需要重新核对工具。

更新后检查工具数量、名称、说明和参数是否符合服务提供方给出的清单。MCP 工具由服务端定义，平台页面没有提供手工编辑工具参数的入口。

七、调试工具

在服务详情的工具列表中点击 调试。

调试页会根据服务端定义展示参数名称、类型、必填状态、默认值和参数说明。填写测试值后点击 运行，结果显示在右侧输出区域。

一次“有输出”不等于工具已经可以交付。至少检查：

• 必填参数已填写，参数类型和格式正确；
• 返回结果符合工具名称和说明；
• 正常输入、空结果和异常输入均已测试；
• 输出不包含 Token、客户端密钥、患者敏感信息或内部调试信息；
• 涉及外部写入的工具只影响测试数据；
• 多次运行的耗时处于可接受范围。

常见问题可按下面的顺序定位：

现象	优先检查
服务无法连接	服务 URL、网络连通性和服务端状态
授权失败	动态客户端注册、客户端 ID、客户端密钥和重新授权
固定 Token 无效	请求头名称、值和凭证是否过期
服务正常但没有工具	点击更新，并核对服务端是否提供工具
工具参数不正确	请服务端修正工具定义，再回到平台更新
工具运行超时	服务端耗时、普通超时和 SSE 读取超时
有返回但结果不可用	工具说明、输入值和服务端返回内容

八、在应用中使用 MCP

工具调试成功后，进入目标 Agent 或 AgentLite 的 编排 页面，在工具区域选择 MCP 服务中的具体工具并开启。入口见应用编排中的工具配置。

应用侧至少完成两类验证：

1. 提出一个必须依赖该工具才能回答的问题，确认模型选择了正确工具；
2. 模拟服务失败或无结果，确认应用不会编造数据，并能给出符合业务要求的提示。

工具已添加不代表本次运行一定调用。需要结合日志与分析或链路追踪，核对实际使用的工具、输入参数和返回结果。

九、服务设置与重新授权

点击服务卡片右上角 …，可以选择 服务设置、重新授权 和 删除服务。

点击 服务设置 后，会打开 编辑 MCP 服务 弹窗。可以修改：

• 服务图标、所属分组、服务名称和服务类型；
• 服务 URL、服务器标识和服务器描述；
• 动态客户端注册、客户端 ID 和客户端密钥；
• 额外请求头；
• 超时时间和 SSE 读取超时时间。

修改 URL、服务器标识、认证、请求头或超时后，按下面的顺序验证：

1. 必要时执行重新授权；
2. 打开服务详情检查健康状态；
3. 点击更新重新获取工具；
4. 调试所有受影响工具；
5. 在引用该服务的应用中完成回归测试；
6. 发布后观察日志和错误情况。

十、更新与删除

服务卡片上的 引用次数 表示该服务被使用的累计次数，仅供参考，不代表当前有多少应用正在使用该服务。

建议按以下顺序维护：

服务端或连接配置发生变化
→ 更新工具列表
→ 对比工具名称和参数
→ 重新调试受影响工具
→ 在应用中回归测试
→ 观察上线后的日志

删除 MCP 服务时，平台不会校验服务是否被应用引用，确认后将直接删除，且删除操作不可恢复。

十一、交付前检查表

• 服务 URL 来自可信的服务提供方，平台网络可以访问；
• 服务器标识在工作空间内唯一；
• 认证、请求头和凭证配置符合服务方要求；
• 文档、截图和调试输出中没有泄露 Token 或客户端密钥；
• 服务健康状态正常，工具列表已经更新；
• 工具名称、说明、参数和服务方清单一致；
• 正常、空结果、异常输入和超时场景均已调试；
• Agent 能够选择正确工具，失败时不会编造结果；
• 已评估服务变更对现有引用应用的影响。