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 的工具。一次调用可以概括为:
- Harness 加载对应的 MCP 客户端配置。
- 客户端与 Server 建立连接并完成协议协商。
- 客户端读取 Server 提供的工具列表。
- 工具被适配并注册到 Harness 的工具运行时。
- 模型根据当前任务选择工具并提供参数。
- Harness 对调用执行相应检查,再由 MCP 客户端向 Server 发起请求。
- Server 执行操作并返回结果。
- 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_resourceslist_mcp_resource_templatesread_mcp_resource
调用时需要显式指定 Server;读取资源还需要指定资源标识。资源内容是在调用读取后进入会话,而不是配置 Server 时自动把所有文档加载进上下文。
服务端没有资源能力时,资源列表可能为空;这不一定意味着连接失败。
服务端指引:帮助理解服务
Server 可以提供说明文字。当前官方客户端会将其作为服务端指引纳入系统提示组装。
服务端指引可能有助于模型理解工具,但它来自外部服务。部署者仍应审查 Server 的来源与行为;不应把任何外部文字都当作可以覆盖用户要求、权限策略或安全边界的指令。
当前客户端文档还说明,MCP 提示模板不在其支持范围内。使用时应核对实际版本,不要把 Server 的所有协议能力都视为 Harness 已经支持。
五、配置时需要确认什么?
本文不提供需要特定服务地址、安装包或凭据才能运行的配置代码。不同 Server 的启动方式和参数不同,直接套用其他服务的配置容易产生误导。
接入前,至少确认以下事项:
| 检查项 | 需要明确的内容 |
|---|---|
| Server 身份 | 谁提供和维护该服务,是否值得信任 |
| 传输方式 | 当前版本支持的连接方式及服务端要求 |
| 调用范围 | 应在哪个 Agent 或部署范围内暴露 |
| 凭据 | 使用哪个账号,具备哪些数据访问权限 |
| 工具能力 | 哪些工具只读,哪些工具有写入或外部副作用 |
| 网络与运行环境 | Server 在哪里运行,能够访问哪些资源 |
| 失败处理 | 连接失败、超时或服务端错误时如何处理 |
当前官方 Manager 文档列出的传输方式包括 stdio 和 streamable-http。前者涉及启动本地子进程,后者涉及连接远端服务;两者的凭据、网络和进程边界需要分别评估。
官方 Manager 还支持通过凭据引用模板解析敏感值。配置本身可能被管理界面读取,因此不应把明文密钥直接写入会被共享的配置文件或博客示例。
工作区沙箱与外部服务权限不是同一回事
第 10 篇介绍的文件沙箱可以约束某些本地执行路径,但 MCP Server 可能是另一个进程或远端服务。
因此:
- Agent 对本地工作区是只读,并不自动保证远端 MCP 工具只读。
- MCP 服务账号拥有写权限时,相关工具可能产生外部副作用。
- 本地
stdioServer 的进程权限和远端 Server 的账号权限,都需要单独检查。 - 某个操作是否需要审批,取决于当前工具管线和部署策略,不能假设每次 MCP 调用都会弹出审批。
六、实践:通过只读 MCP Server 查询知识库
下面设计一条最小化的验证路径。目标是确认 Agent 能通过指定 Server 搜索并读取一份测试文档,不创建或修改外部数据。
实验前提
准备一个已由维护者配置好的测试 MCP Server,假设其本地名称为 knowledge。该服务需要满足:
- 使用专门的测试数据或可公开给本次实验的文档。
- 服务账号仅具备完成查询所需的只读权限。
- Server 提供可用于检索或读取内容的能力。
- 当前 Agent 所在范围能够看到该 Server。
- 当前环境已按安装版本的文档配置 MCP 客户端。
knowledge 只是本文的示例名称;实际服务名和工具名以环境中发现的结果为准。
第一步:确认服务状态
通过当前部署提供的设置或诊断方式,确认:
- Server 配置已启用。
- 连接状态正常,或至少没有明显的启动错误。
- 当前 Session 所在范围可以使用该 Server。
- 服务端实际暴露了预期的只读能力。
如果客户端支持探测功能,可以先探测测试 Server;但探测成功只说明当时的连接和发现路径可用,不代表后续每次调用都会成功。
第二步:提出只读任务
向 Agent 给出明确要求:
请使用
knowledge测试服务查找标题包含“测试接入说明”的文档。只允许搜索和读取,不创建、修改或删除任何内容。返回文档标题、能定位文档的标识,以及与你的结论直接相关的摘要;找不到时说明未找到。
这里不预设 Server 的具体工具名。Agent 应使用当前环境实际发现的工具,而不是编造一个看起来合理的名称。
第三步:区分搜索与读取
如果 Server 提供搜索工具,Agent 可以先搜索,再按服务实际提供的能力读取目标文档。
如果 Server 使用 MCP 资源暴露文档,则应根据当前环境的资源工具:
- 指定
knowledge作为 Server。 - 发现资源或资源模板。
- 选择需要读取的资源。
- 使用同一个 Server 名称读取该资源。
不要把搜索结果摘要当作完整文档,也不要假设每个 MCP Server 同时支持工具和资源。
第四步:核对结果
检查最终回答:
- 是否使用了预期的测试 Server。
- 返回的标题和文档标识是否与服务端记录一致。
- 摘要是否有读取结果作为依据。
- 找不到文档时,是否如实说明。
- 是否把服务端错误误写成“没有结果”。
- 是否发生了任何超出只读范围的操作。
本实践验证的是当前服务、账号和 Agent 范围下的一条调用路径,不能证明其他 Server 或其他工具也具有相同权限边界。
七、如何理解权限和数据边界?
MCP 连接至少涉及三方:
- 用户与 Harness:提出任务并配置可用能力。
- MCP 客户端:发现工具、转发调用并处理结果。
- 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 读取到了过期内容
检查服务端数据更新时间,并重新查询或读取。当前资源组件文档说明,其不支持资源订阅和更新通知;之前已经写入会话历史的读取结果也不会自动更新。
九、接入外部工具的工程建议
- 先只读,后写入。 先验证连接、身份和数据范围,再根据任务需要接入有副作用的工具。
- 使用最小权限凭据。 凭据的权限应与服务用途相称,并避免在配置和日志中暴露明文。
- 明确服务归属。 工具名称、服务维护者和作用域应能帮助排查调用实际发往哪里。
- 检查失败语义。 区分无结果、无权限、连接失败和服务端执行失败。
- 对副作用操作设计核对方式。 超时或中断后,先确认外部状态,再考虑重试。
- 控制返回内容。 优先读取完成任务所需的资料,避免将大量无关或敏感数据带入会话。
- 固定并验证版本。 升级 Harness 或 Server 后,检查工具列表、参数、权限与关键调用路径。
总结
MCP 让 DeepSeek Harness 能把外部 Server 提供的工具和资源接入 Agent 工作流,但完整链路包含连接、发现、注册、调用、权限和结果处理多个阶段。
今天需要记住四点:
- Skill 提供任务方法;MCP 工具和资源提供外部能力。
- 工具名带有 Server 命名空间,便于区分不同来源。
- 资源按需发现和读取,工具调用与资源读取是不同路径。
- 本地沙箱、MCP Server 凭据和外部系统权限需要分别检查。
下一篇,我们将讨论 上下文压缩和预算:当会话历史、工具结果和外部资料不断增加时,Harness 如何管理模型能够看到的内容。
参考资料
- DeepSeek Harness 官方源码:MCP 子系统文档
- DeepSeek Harness 官方源码:MCP Client 包说明
- DeepSeek Harness 官方源码:MCP Manager 包说明
- DeepSeek Harness 官方源码:MCP Resources 包说明
- DeepSeek Harness 官方源码:工具目录
- 点赞
- 收藏
- 关注作者
评论(0)