MCP 与外部工具

举报
yd_229544978 发表于 2026/11/18 01:09:21 2026/11/18
【摘要】 DeepSeek Harness 20 天实战:第 13 天——MCP 与外部工具上一篇,我们通过 Skill 将可复用的任务步骤组织成按需加载的指令。Skill 能告诉 Agent“如何做”,但它本身并不自动提供访问外部系统的能力。如果任务需要查询知识库、读取外部文档或调用业务系统,Agent 还需要相应的工具。MCP 提供了一种连接外部工具和资源的协议方式。今天我们以一个只读查询内部知...

DeepSeek Harness 20 天实战:第 13 天——MCP 与外部工具

上一篇,我们通过 Skill 将可复用的任务步骤组织成按需加载的指令。Skill 能告诉 Agent“如何做”,但它本身并不自动提供访问外部系统的能力。

如果任务需要查询知识库、读取外部文档或调用业务系统,Agent 还需要相应的工具。MCP 提供了一种连接外部工具和资源的协议方式。

今天我们以一个只读查询内部知识库的场景为例,梳理 DeepSeek Harness 如何连接 MCP Server、发现工具、执行调用,以及如何排查连接和权限问题。

版本说明:本文依据截至 2026 年 11 月 18 日可查阅的 DeepSeek Harness 官方主分支源码与文档整理。项目仍处于实验性开发者预览阶段;接口、支持的协议版本和配置可能变化。实际行为以安装版本及其配置为准。

一、从 Skill 到 MCP:指引与能力

先区分三个概念:

概念 主要作用 示例
Skill 提供完成某类任务的方法和约束 如何检查测试配置
MCP 工具 让 Agent 调用外部系统提供的操作 搜索知识库
MCP 资源 让 Agent 按需读取服务端提供的内容 读取一份知识库文档

这几者可以配合使用。一个 Skill 可以指导 Agent 先搜索、再核对文档来源;MCP 工具和资源则提供实际的搜索与读取能力。

但它们不能相互替代:

  • 安装 Skill 不代表外部服务已经连接。
  • 连接 MCP Server 不代表 Agent 已经了解项目的全部工作流程。
  • 工具可以读取数据,也不代表它只能读取当前任务需要的数据。

因此,接入外部能力时,既要确认“怎么用”,也要确认“能访问什么”。

二、DeepSeek Harness 中的 MCP 组件

当前官方源码将 MCP 支持拆成几个组件:

组件 主要职责
dsh-mcp-client 连接一个 MCP Server,发现其工具并接入 Harness
dsh-mcp-manager 管理由设置驱动的多个 MCP Server 实例及其状态
dsh-mcp-resources 为可见的 Server 提供共享资源发现与读取工具
工具运行时 接收注册后的工具,并参与执行、权限检查和结果处理

官方文档说明,MCP Server 需要显式配置;没有配置任何 Server 的调用范围,不会因此自动获得 MCP 工具。

Client 与 Manager 的区别

dsh-mcp-client 对应一个服务连接。需要连接多个服务时,可以配置多个客户端实例。

dsh-mcp-manager 则用于管理一组客户端实例。当前文档描述了启用、停用、重启、状态查看和探测等能力。是否存在可操作的设置界面,取决于具体产品和部署组合。

不要把“Manager 中存在一条配置”和“该 Server 已经成功连接”当作同一件事。配置可以存在,而连接仍可能失败。

三、一次 MCP 工具调用的路径

假设已配置一个名为 knowledge 的 MCP Server,它提供一个名为 search 的工具。一次调用可以概括为:

  1. Harness 加载对应的 MCP 客户端配置。
  2. 客户端与 Server 建立连接并完成协议协商。
  3. 客户端读取 Server 提供的工具列表。
  4. 工具被适配并注册到 Harness 的工具运行时。
  5. 模型根据当前任务选择工具并提供参数。
  6. Harness 对调用执行相应检查,再由 MCP 客户端向 Server 发起请求。
  7. Server 执行操作并返回结果。
  8. Harness 将结果交给 Agent,供后续分析和回答使用。

这条路径中有多个可能失败的位置:连接、工具发现、权限检查、参数校验、服务端执行和结果处理。排查时先定位失败阶段,比反复重试同一调用更有效。

工具为什么带 Server 名称?

当前官方客户端将模型可见的工具命名为类似以下形式:

mcp__<serverName>__<rawName>

在上面的例子中,模型侧可能看到:

mcp__knowledge__search

其中:

  • knowledge 是本地配置的 Server 名称。
  • search 是 Server 提供的原始工具名。

如果另一个 Server 也提供 search,带 Server 名称的公开名称有助于区分二者。官方实现对不符合名称约束的情况还会做规范化处理,因此复杂名称的实际结果应以工具列表为准。

发送给 MCP Server 的调用使用的是该 Server 的原始工具名;模型侧名称用于 Harness 内部注册与区分。

四、工具、资源和服务端指引有什么区别?

MCP Server 可以提供不同类型的能力。当前 DeepSeek Harness 相关组件对以下内容分别处理:

工具:执行一个操作

工具通常有名称、描述和输入参数。Agent 选择工具后,客户端向 Server 发起调用。

工具既可能是只读查询,也可能创建、修改或删除外部数据。不能因为它通过 MCP 暴露,就假设它是只读的。 应结合工具定义、服务端权限和实际策略判断。

资源:按需读取内容

当前官方 dsh-mcp-resources 提供共享的资源发现和读取工具:

  • list_mcp_resources
  • list_mcp_resource_templates
  • read_mcp_resource

调用时需要显式指定 Server;读取资源还需要指定资源标识。资源内容是在调用读取后进入会话,而不是配置 Server 时自动把所有文档加载进上下文。

服务端没有资源能力时,资源列表可能为空;这不一定意味着连接失败。

服务端指引:帮助理解服务

Server 可以提供说明文字。当前官方客户端会将其作为服务端指引纳入系统提示组装。

服务端指引可能有助于模型理解工具,但它来自外部服务。部署者仍应审查 Server 的来源与行为;不应把任何外部文字都当作可以覆盖用户要求、权限策略或安全边界的指令。

当前客户端文档还说明,MCP 提示模板不在其支持范围内。使用时应核对实际版本,不要把 Server 的所有协议能力都视为 Harness 已经支持。

五、配置时需要确认什么?

本文不提供需要特定服务地址、安装包或凭据才能运行的配置代码。不同 Server 的启动方式和参数不同,直接套用其他服务的配置容易产生误导。

接入前,至少确认以下事项:

检查项 需要明确的内容
Server 身份 谁提供和维护该服务,是否值得信任
传输方式 当前版本支持的连接方式及服务端要求
调用范围 应在哪个 Agent 或部署范围内暴露
凭据 使用哪个账号,具备哪些数据访问权限
工具能力 哪些工具只读,哪些工具有写入或外部副作用
网络与运行环境 Server 在哪里运行,能够访问哪些资源
失败处理 连接失败、超时或服务端错误时如何处理

当前官方 Manager 文档列出的传输方式包括 stdio 和 streamable-http。前者涉及启动本地子进程,后者涉及连接远端服务;两者的凭据、网络和进程边界需要分别评估。

官方 Manager 还支持通过凭据引用模板解析敏感值。配置本身可能被管理界面读取,因此不应把明文密钥直接写入会被共享的配置文件或博客示例。

工作区沙箱与外部服务权限不是同一回事

第 10 篇介绍的文件沙箱可以约束某些本地执行路径,但 MCP Server 可能是另一个进程或远端服务。

因此:

  • Agent 对本地工作区是只读,并不自动保证远端 MCP 工具只读。
  • MCP 服务账号拥有写权限时,相关工具可能产生外部副作用。
  • 本地 stdio Server 的进程权限和远端 Server 的账号权限,都需要单独检查。
  • 某个操作是否需要审批,取决于当前工具管线和部署策略,不能假设每次 MCP 调用都会弹出审批。

六、实践:通过只读 MCP Server 查询知识库

下面设计一条最小化的验证路径。目标是确认 Agent 能通过指定 Server 搜索并读取一份测试文档,不创建或修改外部数据。

实验前提

准备一个已由维护者配置好的测试 MCP Server,假设其本地名称为 knowledge。该服务需要满足:

  • 使用专门的测试数据或可公开给本次实验的文档。
  • 服务账号仅具备完成查询所需的只读权限。
  • Server 提供可用于检索或读取内容的能力。
  • 当前 Agent 所在范围能够看到该 Server。
  • 当前环境已按安装版本的文档配置 MCP 客户端。

knowledge 只是本文的示例名称;实际服务名和工具名以环境中发现的结果为准。

第一步:确认服务状态

通过当前部署提供的设置或诊断方式,确认:

  1. Server 配置已启用。
  2. 连接状态正常,或至少没有明显的启动错误。
  3. 当前 Session 所在范围可以使用该 Server。
  4. 服务端实际暴露了预期的只读能力。

如果客户端支持探测功能,可以先探测测试 Server;但探测成功只说明当时的连接和发现路径可用,不代表后续每次调用都会成功。

第二步:提出只读任务

向 Agent 给出明确要求:

请使用 knowledge 测试服务查找标题包含“测试接入说明”的文档。只允许搜索和读取,不创建、修改或删除任何内容。返回文档标题、能定位文档的标识,以及与你的结论直接相关的摘要;找不到时说明未找到。

这里不预设 Server 的具体工具名。Agent 应使用当前环境实际发现的工具,而不是编造一个看起来合理的名称。

第三步:区分搜索与读取

如果 Server 提供搜索工具,Agent 可以先搜索,再按服务实际提供的能力读取目标文档。

如果 Server 使用 MCP 资源暴露文档,则应根据当前环境的资源工具:

  1. 指定 knowledge 作为 Server。
  2. 发现资源或资源模板。
  3. 选择需要读取的资源。
  4. 使用同一个 Server 名称读取该资源。

不要把搜索结果摘要当作完整文档,也不要假设每个 MCP Server 同时支持工具和资源。

第四步:核对结果

检查最终回答:

  • 是否使用了预期的测试 Server。
  • 返回的标题和文档标识是否与服务端记录一致。
  • 摘要是否有读取结果作为依据。
  • 找不到文档时,是否如实说明。
  • 是否把服务端错误误写成“没有结果”。
  • 是否发生了任何超出只读范围的操作。

本实践验证的是当前服务、账号和 Agent 范围下的一条调用路径,不能证明其他 Server 或其他工具也具有相同权限边界。

七、如何理解权限和数据边界?

MCP 连接至少涉及三方:

  1. 用户与 Harness:提出任务并配置可用能力。
  2. MCP 客户端:发现工具、转发调用并处理结果。
  3. MCP Server 与外部系统:执行操作并根据自身权限返回数据。

一次调用是否安全,不能只检查其中一方。

例如,用户要求“查询一篇文档”,但如果服务账号可以读取整个组织的敏感资料,那么账号的实际授权范围可能远大于当前任务。更合适的做法是为测试和生产任务分别配置最小必要权限,并限制凭据的暴露范围。

把外部结果当作数据核对

Server 返回的文本可能包含错误、过期信息,或者要求 Agent 执行额外操作的内容。Agent 应结合用户任务与可信规则处理这些文本;对其中提出的额外动作,应重新检查是否属于授权范围。

注意会话记录中的数据

资源文本和工具结果可能进入会话历史。读取文档前应考虑内容是否允许进入当前 Session,以及该 Session 的访问、保留和删除策略。

这也与第 09 篇有关:会话能持久化,意味着进入历史的外部内容可能在后续恢复时仍然可见。

八、常见问题排查

1. Server 已配置,但工具没有出现

检查:

  • Server 是否启用、连接是否成功。
  • 当前 Agent 的作用域是否能看到该 Server。
  • Server 是否实际声明了工具能力。
  • 服务端返回的工具列表是否有效。
  • 本地 Server 名称是否与同一作用域中的其他配置冲突。
  • 当前部署是否加载了相应 MCP 客户端。

官方客户端文档说明,初始连接失败时,Harness 仍可能启动,但该 Server 的工具不会出现,并会记录错误。因此,“应用启动成功”不等于“MCP 连接成功”。

2. 资源工具可见,但读取时报连接错误

共享资源工具是否可见,与某次 Server 连接是否成功不是完全相同的状态。检查指定的 Server 名称、连接状态和服务端资源能力,再查看具体错误。

3. 资源列表为空

先区分:

  • Server 不支持资源能力。
  • Server 支持资源,但当前账号没有可见资源。
  • 当前筛选或分页条件没有返回目标。
  • 请求失败,客户端显示的是错误而不是空列表。

不要把空列表直接解释为“目标文档一定不存在”。

4. 工具调用超时或失败

检查服务状态、网络连接、凭据、参数和服务端日志。对于可能产生副作用的操作,超时不代表外部操作一定没有发生;重试前应先核对外部系统状态。

5. 同名工具来自不同 Server

查看带 Server 前缀的实际工具名,并确认调用的是预期服务。不要只根据末尾的 search 或其他原始名称判断目标。

6. Agent 读取到了过期内容

检查服务端数据更新时间,并重新查询或读取。当前资源组件文档说明,其不支持资源订阅和更新通知;之前已经写入会话历史的读取结果也不会自动更新。

九、接入外部工具的工程建议

  1. 先只读,后写入。 先验证连接、身份和数据范围,再根据任务需要接入有副作用的工具。
  2. 使用最小权限凭据。 凭据的权限应与服务用途相称,并避免在配置和日志中暴露明文。
  3. 明确服务归属。 工具名称、服务维护者和作用域应能帮助排查调用实际发往哪里。
  4. 检查失败语义。 区分无结果、无权限、连接失败和服务端执行失败。
  5. 对副作用操作设计核对方式。 超时或中断后,先确认外部状态,再考虑重试。
  6. 控制返回内容。 优先读取完成任务所需的资料,避免将大量无关或敏感数据带入会话。
  7. 固定并验证版本。 升级 Harness 或 Server 后,检查工具列表、参数、权限与关键调用路径。

总结

MCP 让 DeepSeek Harness 能把外部 Server 提供的工具和资源接入 Agent 工作流,但完整链路包含连接、发现、注册、调用、权限和结果处理多个阶段。

今天需要记住四点:

  1. Skill 提供任务方法;MCP 工具和资源提供外部能力。
  2. 工具名带有 Server 命名空间,便于区分不同来源。
  3. 资源按需发现和读取,工具调用与资源读取是不同路径。
  4. 本地沙箱、MCP Server 凭据和外部系统权限需要分别检查。

下一篇,我们将讨论 上下文压缩和预算:当会话历史、工具结果和外部资料不断增加时,Harness 如何管理模型能够看到的内容。

参考资料

  • DeepSeek Harness 官方源码:MCP 子系统文档
  • DeepSeek Harness 官方源码:MCP Client 包说明
  • DeepSeek Harness 官方源码:MCP Manager 包说明
  • DeepSeek Harness 官方源码:MCP Resources 包说明
  • DeepSeek Harness 官方源码:工具目录
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。