使用 MCP 实例连接外部工具
智能体开发服务平台（AgentWorks）通过 MCP 实例连接平台外运行的 MCP Server，让智能体发现并调用其中的工具。MCP 实例保存实际使用的 Server URL、超时、TLS 和 Header 配置。
什么时候直接使用 MCP 实例
MCP 实例就是一条已经配置好、可以直接使用的 MCP 连接。你可以在 MCP 管理 中从头创建一个 MCP 实例，直接填写 Server URL、超时、TLS 和 Header；不需要先创建 MCP 模板。
如果连接信息不需要随智能体实例或用户变化，直接使用 MCP 实例通常最简单。常见场景包括：
- 一个智能体连接一个地址固定的 MCP Server。
- 多个智能体共同使用同一个公开 MCP Server，例如
https://learn.microsoft.com/api/mcp。 - 团队希望多个智能体通过同一个服务账号和同一组 Header 访问内部工具。
- 你正在搭建原型或验证连接，希望先用最少配置完成工具发现和真实调用。
- 团队希望集中维护一条连接，并且可以接受修改它时所有引用方一起受到影响。
创建 MCP 实例后，在智能体模板中选择 MCP - 实例 并引用它。以后从该智能体模板创建的智能体实例会直接使用这条连接，不会再生成新的 MCP 实例。
只有当不同智能体实例需要填写不同的访问令牌、Header、环境、区域、客户或工作区参数时，才需要选择 MCP - 模板。AgentWorks 会在创建智能体实例时，根据参数生成一条独立连接。具体方法参见使用 MCP 模板为智能体实例按需生成连接。
不同的 MCP 实例不代表外部身份和权限已经自动隔离。只有这些实例实际使用不同凭证，且 MCP Server 按凭证区分身份和授权时，外部权限范围才会不同。
MCP 并不是接入工具的唯一方式。平台已经提供目标工具时，使用平台工具包；工具需要由调用智能体的业务系统执行时，使用用户工具包；需要在隔离环境中执行命令或处理文件时，使用沙箱。
准备远程 MCP Server
在平台外部署 MCP Server，并提供可从 AgentWorks 访问的 HTTPS 地址。用户控制台支持 Streamable HTTP 传输方式。
上线前确认：
- Server URL 可以从平台网络访问。
- TLS 证书有效。
- 认证请求头已经准备。
- 工具名称和输入 schema 稳定。
- Server 对重复或超时调用有安全处理。
创建并测试 MCP 实例
本节用于创建一条可以直接使用的固定连接，并确认 AgentWorks 能从 MCP Server 取得工具信息。完成配置后，先验证工具发现，再通过智能体实例和 Trace 验证一次真实工具调用。
如果想先使用一个不要求自备认证 Header 的公开服务走完整个流程，参见构建使用公开文档 MCP 的技术文档助手。该实战包含连接、工具发现、搜索、页面读取和 Trace 验证，只使用公开、非敏感问题；其他 MCP Server 是否需要认证取决于服务提供方。
使用有权创建和管理 MCP 资源的账号完成以下操作。遇到权限提示时，请联系管理员按排查权限问题检查授权。
创建 MCP 实例
以下步骤会从头创建一个独立的 MCP 实例，而不是从 MCP 模板生成实例。
打开新建 MCP 实例页面。
也可从左侧导航进入 MCP 管理，选择 实例，再选择新建操作。
填写实例名称和说明，并配置与目标服务一致的 Server URL、超时和请求头。
仅在受控测试环境排查自签名证书时启用 跳过 TLS 校验。
创建实例。
一个 MCP 实例可以被多个智能体模板引用。只有这些引用方可以接受共享同一地址、Header、外部权限和变更影响时，才复用同一个实例；否则分别创建实例，或改用 MCP 模板。
确认 MCP 实例的来源
直接新建的 MCP 实例和根据 MCP 模板生成的 MCP 实例，创建后都是可以独立使用和管理的连接，因此会统一显示在 MCP 管理 的 实例 列表中。
需要确认某个实例的来源时，打开实例详情：
- 显示 来源 MCP 模板：该实例由相应的 MCP 模板生成；选择模板名称可以查看原模板。
- 未显示 来源 MCP 模板：该实例是在 MCP 管理中直接创建的。
测试连接并查看工具列表
连接是否可用、能否取得工具列表和工具能否完成任务，需要分别检查：
- 在 MCP 实例中选择 测试连接。成功表示 AgentWorks 能与目标服务建立 MCP 连接并收到服务响应。
- 查看 工具列表，确认预期工具已经列出，并能查看工具说明和输入参数。
需要为 MCP 工具配置确认规则时，在 工具列表 中复制目标工具的名称，再展开该工具的输入 schema，复制顶层 properties 中的参数名。工具名称和参数名必须与工具定义完全一致。参见找到工具名称和参数名。
连接测试和工具列表都不运行具体工具。完成下面的插件关联后，再通过智能体实例实际调用工具，验证参数、权限、中断、超时和业务结果。
将 MCP 实例添加到智能体模板
MCP 实例只有被智能体模板引用，并进入智能体实例的运行配置后，智能体才能使用其中的工具。
- 创建或编辑智能体模板，打开 插件配置。
- 单击 添加插件。
- 选择 MCP - 实例，再选择已经完成连接测试的 MCP 实例。
- 保存智能体模板。
- 在智能体模板详情页的 插件 页签中确认 MCP 类型、名称和资源 ID。
- 创建或更新用于测试的智能体实例。
需要让平台在创建智能体实例时按参数生成 MCP 实例时，不要在这里选择固定实例；改为将 MCP 模板添加到智能体模板。
在智能体实例中验证工具
能建立连接、看到工具列表后，还需要确认工具在实际任务中能正常完成。完成插件关联后：
- 创建或更新测试智能体实例。
- 发送能明确触发目标工具的输入。
- 在 Trace 中确认工具名称、输入参数和结果。
- 使用无权限或无效参数测试失败路径。
- 检查 MCP Server 侧是否产生预期副作用。
工具若返回文件链接或非图片文件，本轮对话会继续。Trace 和后续推理里看到的是链接，或类型与长度说明，不是文件正文。图片和文本内容仍按原样进入后续推理。不要把缺少文件正文当成这次调用失败。
工具发现成功但智能体实例调用失败时，分别检查实例配置、Server 业务权限、输入参数和超时。MCP 配置页面不提供独立审批开关；在智能体模板的 工具权限 中配置 MCP 调用的自动拒绝、自动批准或人工审批。工具权限不能代替 MCP Server 自身的身份验证和业务授权。
维护 MCP 实例
MCP 投入使用后，需要在变更连接配置、轮换凭证、排查故障或删除资源时控制影响范围，并完成相应验证。无论实例是直接创建还是由 MCP 模板生成，均按本节管理实际连接。
修改地址或超时
修改共享 MCP 实例会改变多个智能体所依赖的连接。不要仅根据 MCP 实例已经保存判断运行中的智能体实例已经使用新配置；变更后应更新相关智能体实例，并通过工具列表和真实调用确认生效。
变更生产连接前：
- 盘点引用当前 MCP 实例的智能体模板和智能体实例。
- 优先创建替代 MCP 实例并配置新的 Server URL、超时或 Headers。
- 在替代 MCP 实例上完成连接测试，再让测试智能体实例执行真实工具调用。
- 分阶段切换生产智能体模板的 MCP 引用，逐个编辑并保存关联的智能体实例，再验证真实工具调用。
- 验证后再删除旧引用和旧实例。
直接编辑共享实例适合可以接受同时切换所有相关智能体模板和智能体实例的场景。编辑后立即重新测试 工具列表和真实调用。
轮换 Header 凭证
MCP Header 可以在详情中显示或编辑，不能当作由平台托管的不可见密钥。轮换时使用外部密钥系统生成最小权限凭证，并优先采用替代实例流程。
如果外部 MCP Server 允许新旧凭证并存：
- 创建使用新 Header 的替代 MCP 实例。
- 完成连接、工具发现和智能体实例调用测试。
- 切换引用该 MCP 实例的智能体模板和智能体实例。
- 撤销旧凭证。
- 删除旧 MCP 实例。
如果只能原位替换 Header，应安排维护窗口。保存新值后立即测试，失败时恢复仍有效的旧值。
保护 MCP 凭证
MCP Header 是控制台可展示和编辑的连接配置，不是只写不可读的密钥保管项。凭证生成、审批、备份和轮换记录应由外部密钥系统负责。
- 为 MCP 创建最小权限凭证。
- 不复用个人令牌。
- 在外部密钥系统记录轮换责任。
- 修改共享实例前确认影响范围。
- 生产环境不要启用 跳过 TLS 校验。
处理连接问题
- 测试连接失败：检查 Server URL、网络、证书和 Headers。
- 连接测试成功，但 工具列表加载失败或为空：检查 MCP Server 是否提供工具，以及所用凭证是否允许读取工具列表。
- 智能体实例调用超时：核对 MCP 实例的超时设置、Server 处理时间和工具返回结果。连接测试与实际工具调用的等待时间可能不同；重试写入类工具前，先到外部系统确认上次操作是否已经完成。
- 需要限制工具执行：在 MCP Server 和所用凭证中限制身份、权限和可执行操作。智能体模板中的审批处理规则不能代替 Server 端授权。
删除 MCP 实例
删除 MCP 实例不可撤销，并可能让引用它的智能体模板和智能体实例失去工具。先移除或替换所有智能体模板引用、更新相关智能体实例并完成回归测试，再删除实例。
删除 AgentWorks 中的 MCP 实例不会删除平台外运行的 MCP Server，也不会撤销外部凭证。删除 MCP 模板和检查生成实例的方法参见管理 MCP 模板和生成的实例。