MCP 服务¶
MCP（Model Context Protocol，模型上下文协议）服务用于让 Agent 连接外部工具、数据源或内部系统。通过 MCP 服务，Agent 可以在授权范围内查询数据、调用工具、访问系统能力或执行特定操作。
与技能不同，MCP 服务更接近“工具入口”。如果 MCP 服务连接生产系统、客户数据或可执行写操作的系统，需要特别关注权限、数据范围和操作风险。
如果您还不确定应该使用 Skill、MCP 服务还是组合使用，请先阅读 Skill 与 MCP：如何选择。
配置方式¶
Obsy Agent Teams 使用“全局配置、按 Agent 启用、运行时确认”的方式管理 MCP 服务：
| 步骤 | 操作位置 | 说明 |
|---|---|---|
| 1 | 设置中心的全局配置 | 新增、编辑或删除当前空间可用的 MCP 服务，并检查配置和工具信息。 |
| 2 | Agent 工作台的 MCP 服务 | 为当前 Agent 开启需要使用的服务，并等待运行时完成安装和激活。 |
| 3 | Agent 任务 | 描述任务目标，由 Agent 在已激活工具中选择并调用合适的能力。 |
flowchart LR
A[全局配置 MCP 服务] --> B[为目标 Agent 开启]
B --> C[Agent 运行时安装并激活]
C --> D[查看实际可用工具]
D --> E[在任务中使用]全局配置只决定空间中有哪些 MCP 服务，不会自动把服务开放给所有 Agent。Agent 工作台中的开关只影响当前 Agent，也不会改变其他 Agent 的配置。
开始前准备¶
配置前，请确认：
- MCP Server 的来源可信，并提供可用于当前运行环境的配置；
- 目标 Agent 的主机能够访问 MCP Server、软件包仓库和相关业务系统；
- 如使用本地
stdio服务，运行环境已具备启动命令所需的 Node.js、Python 或其他依赖； - 如使用远程 HTTP 服务，网络、代理、证书和鉴权信息已经准备完成；
- 当前账号具有全局 MCP 管理权限，以及目标 Agent 的管理权限；
- 已明确 MCP 工具需要访问的数据范围和可能执行的写操作。
第一步：在全局配置中管理 MCP 服务¶
点击页面右上角的个人头像，进入设置中心的 Agent 配置 > MCP 服务。这里是空间级 MCP 能力池，可以新增、搜索、编辑或删除服务，并在支持发现时查看工具列表。服务是否对某个 Agent 生效，需要在该 Agent 的工作台中单独控制。
新增 MCP 服务¶
- 点击新建 MCP 服务。
- 选择表单或高级 JSON配置方式。
- 根据 MCP Server 提供方的说明填写连接信息。
- 保存配置。
- 在服务卡片中检查配置状态和已发现的工具。
选择配置方式¶
| 配置方式 | 适用场景 | 配置内容 |
|---|---|---|
| 表单 | 推荐用于常见的单个 MCP 服务。 | 填写名称、连接类型及对应的启动命令或 URL；还可以按需添加参数、环境变量、请求头、工作目录和超时时间。 |
| 高级 JSON | 适用于从服务提供方复制完整配置，或配置表单暂时无法表达的高级选项。 | 按 MCP Server 提供方给出的 JSON 配置进行填写。 |
表单支持 STDIO、流式 HTTP 和兼容的 SSE 类型。选择 STDIO 时，需要填写运行服务所需的启动命令；选择远程连接时，需要填写服务 URL。页面会根据所选类型展示对应字段。
填写表单字段¶
所有类型都需要填写以下字段：
| 字段 | 是否必填 | 说明 |
|---|---|---|
| 名称 | 是 | MCP 服务在当前工作空间中的展示名称。建议使用能体现服务来源或用途的名称，方便后续搜索、启用和排查。 |
| 类型 | 是 | 选择 MCP Server 实际支持的连接方式。类型必须与服务提供方给出的接入说明一致。 |
选择 STDIO 时，Agent 会在其运行环境中启动本地进程，并通过标准输入输出与 MCP Server 通信：
| 字段 | 是否必填 | 说明 |
|---|---|---|
| 启动命令 | 是 | 用于启动 MCP Server 的可执行命令，例如 npx、node 或 python。该命令必须已安装并可在 Agent 运行环境中执行。 |
| 参数 | 否 | 按执行顺序逐项填写传给启动命令的参数。命令选项、软件包名称和脚本路径通常填写在这里，每行表示一个独立参数。 |
| 环境变量 | 否 | 以键值对形式提供进程启动时需要的配置。变量名不能重复；只填写该服务运行所需的变量。 |
| 工作目录 | 否 | 启动命令执行时使用的目录。配置文件或脚本依赖相对路径时填写，并确保该目录在 Agent 运行环境中存在且可访问。 |
| 包名 | 否 | 用于标识该 MCP Server 对应的软件包，便于页面展示和识别；不替代启动命令或参数。 |
| 超时时间（秒） | 否 | 等待服务响应的最长时间。未填写时使用系统默认值；服务初始化或查询耗时较长时，可根据实际情况适当增加。 |
选择 流式 HTTP 或 SSE（兼容） 时，Agent 会连接已经部署并可通过网络访问的 MCP Server：
| 字段 | 是否必填 | 说明 |
|---|---|---|
| URL | 是 | MCP Server 的完整访问地址。流式 HTTP 应填写对应的 MCP 接口地址；仅当服务提供方明确要求使用 SSE 兼容连接时选择 SSE，并填写其服务地址。 |
| 请求头 | 否 | 以键值对形式附加到连接请求中，适用于服务提供方要求的鉴权信息、租户标识或其他固定请求头。请求头名称不区分大小写且不能重复。 |
| 超时时间（秒） | 否 | 等待连接或服务响应的最长时间。未填写时使用系统默认值；网络较慢或服务处理时间较长时，可根据实际情况适当增加。 |
凭据安全
环境变量和请求头会成为 MCP 服务配置的一部分。仅填写连接所需的信息，不要使用来源不明的密钥，也不要将配置内容复制到不受控的位置。凭据发生泄露时，应立即在对应系统中轮换或撤销。
表单与高级 JSON 使用同一份配置，切换方式不会自动保存。页面会尽量保留尚未提交的内容；如果当前 JSON 包含多个服务、特殊连接类型或表单无法完整表达的设置，页面会提示继续使用高级 JSON，避免配置内容在切换时丢失。
配置内容应以 MCP Server 提供方的说明为准。不要为了通过校验而猜测命令、参数或地址，也不要把长期密钥直接写入会被多人查看的位置。需要凭据时，应使用团队批准的密钥管理方式。
注意
表单模式一次配置一个 MCP 服务。修改或删除服务前，请先确认哪些 Agent 正在使用该服务。
查看和刷新工具¶
全局服务卡片会展示服务配置状态和工具发现结果。根据服务类型和状态，您可以：
- 展开工具列表，查看工具名称和说明；
- 刷新单个远程 MCP 服务的工具列表；
- 点击刷新全部，更新当前工作空间中支持发现的远程 MCP 服务；
- 在发现失败时查看错误详情；
- 编辑配置；
- 删除服务。
全局配置页展示的是远程 MCP 服务的已发现工具，不代表某个 Agent 已经可以使用这些工具。服务仍需在具体 Agent 中启用，并以该 Agent 工作台的运行状态为准。本地 STDIO 服务运行在 Agent 所在环境中，其工具列表也应在启用后从 Agent 工作台确认。
工具发现中、发现失败、尚未发现和未发现工具是不同状态。刷新过程中，页面可能继续展示上一次成功发现的工具；如果刷新失败，原有列表会保留并提示信息可能已经过期。修复连接或配置问题后，再重新刷新确认。
第二步：在 Agent 配置中启用 MCP 服务¶
MCP 服务新增后，不会自动对所有 Agent 生效：
- 进入目标 Agent 的工作台。
- 打开配置 > MCP 服务。
- 搜索目标服务，并打开该服务的开关。
- 等待当前资源完成保存、安装和激活。
- 展开运行时工具区域，确认工具数量、名称和说明符合预期。
搜索框支持按 MCP 服务名称、运行时工具名称和工具说明筛选，可以直接从目标能力定位对应服务。
每次开关操作只保存当前 MCP 服务，不会重新提交或锁定该 Agent 的全部 MCP 配置。当前服务仍在保存、安装、等待或卸载时，开关会暂时锁定；其他服务仍可独立查看和配置。
建议按 Agent 职责和权限边界启用 MCP 服务。例如生产排障 Agent 可以启用只读查询类 MCP 服务，云成本分析 Agent 可以启用云账单相关服务，普通文档整理 Agent 则不需要连接生产系统。
认识运行状态¶
Agent 工作台会跟踪配置从保存到运行时可用的过程。常见状态包括：
| 状态 | 说明 | 建议 |
|---|---|---|
| 正在保存或等待 Agent | 期望配置已提交，正在等待 Agent 接收。 | 保持 Agent 在线，等待状态继续变化。 |
| 安装中 | Agent 正在准备依赖或连接服务。 | 不要重复切换；检查主机网络和依赖安装能力。 |
| 已激活 | Agent 运行时已加载该 MCP 服务。 | 展开工具区域，核对实际可用工具。 |
| 卸载中 | 服务已关闭，Agent 正在移除运行时资源。 | 等待完成后再重新开启。 |
| 安装失败 | 依赖、配置、网络或连接检查失败。 | 查看错误和排查编号，修复后重新安装。 |
| 需要升级 Agent | 当前 Agent 版本不支持所需配置同步能力。 | 按 Agent 运维文档升级运行服务后重试。 |
| 运行时同步暂停 | 当前配置同步已暂停，历史工具记录不能证明本次配置已经生效。 | 检查 Agent 状态和页面提示，再恢复配置。 |
MCP 工具区域默认收起，标题会显示 Agent 运行时实际上报的工具总数。展开后，可以按组件和传输方式查看工具名称与说明。禁用服务后，工具会立即从当前可用列表中隐藏。
如果新配置安装失败，但上一版本仍在提供工具，页面会明确提示“上一可用版本正在服务”。此时不要把新配置视为已生效，应先修复错误并完成重新安装。
第三步：在任务中调用 MCP 工具¶
MCP 服务启用后，Agent 可以在任务中根据目标调用对应工具。您也可以在任务输入中明确说明希望 Agent 查询哪些对象、使用哪些工具、输出哪些结果。
建议先创建一个低风险测试任务，确认工具可被选择并返回预期结果。例如：
涉及生产环境、客户数据、权限变更或写操作时，请在任务中写清操作范围、预期结果和需要审批的动作，并确认 Agent 的可用范围和行为边界符合团队要求。
最佳实践：接入并验证一个 MCP 服务¶
建议先以单个 Agent、只读工具和非生产范围完成验证，再逐步扩大使用范围：
- 确认服务用途和来源：从 MCP Server 提供方的正式说明获取配置，先确认它会访问哪些数据、提供哪些工具，以及是否包含写操作。
- 使用最小权限配置：优先使用只读凭据，并将可访问的数据范围限制在测试环境或必要的业务对象内。凭据由团队认可的方式管理，不要直接分享给无关成员。
- 在全局配置中检查工具：保存后查看工具发现状态，确认工具名称和说明与预期一致。远程服务的配置发生变化后，应刷新工具列表再继续验证。
- 只为测试 Agent 启用：在目标 Agent 工作台中开启该服务，等待状态变为已激活，并核对运行时实际上报的工具。全局页面已发现工具，不等于 Agent 已经可以使用。
- 运行低风险测试任务：明确指定目标对象、只读要求和输出格式，检查 Agent 是否选择了正确工具、返回了预期数据，并能在工具不可用时说明原因。
- 通过后再扩大范围：确认权限、数据质量和运行稳定性后，再用于生产任务或更多 Agent。涉及写操作时，保留人工确认，并在 Agent 行为边界中写明允许和禁止的操作。
配置、服务版本或凭据调整后，应重新执行工具刷新、运行时确认和低风险测试，不要仅根据之前成功的工具列表判断当前配置仍然可用。
排查 MCP 服务¶
| 现象 | 检查方式 |
|---|---|
| 全局配置无法保存 | 根据页面提示检查必填项；使用高级 JSON 时，检查配置结构、服务名称，以及启动命令或 URL 是否有效。 |
| 服务连接失败 | 查看错误详情，检查地址、网络、代理、证书和鉴权配置。 |
| 工具刷新失败 | 检查服务连接和鉴权信息后重新刷新；页面仍显示旧工具时，以提示的最近成功结果为参考，不要将其视为最新状态。 |
| Agent 工作台找不到服务 | 确认服务仍存在于当前空间的全局配置中，然后重新进入 Agent 工作台检查。 |
| 开关长时间停留在等待状态 | 确认 Agent 在线、版本满足要求，并检查运行服务日志和页面排查编号。 |
| 安装失败 | 检查 stdio 命令、依赖、软件包仓库和主机权限，或远程 HTTP 服务的连通性。 |
| 已激活但没有工具 | 展开工具区域，等待页面自动更新；确认 MCP Server 实际返回了工具列表，且当前组件没有报错。页面提供重试操作时再按提示重试。 |
| 任务没有使用 MCP 工具 | 确认工具已经出现在当前 Agent 的运行时列表，并在任务中说明目标对象和希望使用的能力。 |
使用建议¶
- 只为 Agent 启用与当前职责直接相关的 MCP 服务；
- 优先使用只读或最小权限凭据，并限制目标系统中的数据和操作范围；
- 从可信来源复制配置，升级服务包前检查版本和变更内容；
- 对生产写操作保留人工审批，并在 Agent 行为边界中明确禁止事项；
- 配置变更后，以 Agent 工作台中的运行状态和实际工具列表确认是否生效；
- 定期检查失败、停用和无人使用的服务，及时修复或清理；
- MCP 服务不可用时，要求 Agent 明确说明缺失能力，不要根据不完整数据继续给出确定结论。