第13讲 · MCP 接入——把外部工具世界挂进来

《DeepSeek Harness 从上手到精通》系列 · 第四阶工具开发篇

🎯 目标：通过 MCP 协议复用生态里现成的工具服务器难度 ★★☆ ⏱ 约 25 分钟前置：第 11–12 讲工具链路基础

自己写工具（第 11–12 讲）能解决"专属需求"，但世界上已经有大量现成工具——文件系统、数据库、搜索、各种 SaaS。难道每个都要重写？不必。MCP（Model Context Protocol）就是让 dsh 直接"挂"上这些外部工具服务器的标准协议。系列基于 deepseek-ai/deepseek-harness（0.1.0-rc.5，MIT），preview 阶段以官方 README 为准。

一、MCP 是什么：一分钟科普

MCP 是一套"工具服务器"的开放协议：一个 MCP server 启动后，对外暴露一组"工具 + 资源"，任何支持 MCP 的客户端（Claude Desktop、IDE、以及我们的 dsh）都能连上去，把这些工具当成自己的用。

一句话类比：MCP 之于 AI 工具，就像 USB 之于外设——插上就能用，不用为每个设备单独造接口。dsh 是"宿主"，第三方 server 是"外设"。

MCP 接入示意 — **图 1** dsh 作为 MCP 宿主，接入多个外部工具服务器，工具统一进入作用域注册表。

二、在 dsh 里注册一个 MCP server

核心在 packages/mcp/mcp-client。最常用的是基于 stdio 的 server——dsh 负责拉起进程、做握手、把对方暴露的工具转成内部工具。典型配置（patch 片段，字段名以官方为准）：

# cordis.patch.yml（示意）
mcp:
  servers:
    filesystem:
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
      scope: ["web", "headless"]

这里的 scope 把第 12 讲的作用域概念用上了：你可以只让 MCP 工具在 web 会话出现，headless 不暴露，避免自动化脚本误用。

三、实例：接入文件系统 / 搜索类 MCP 工具

挑两个稳妥的官方 server 上手（社区已有大量实现，按需替换包名）：

filesystem：让模型读写指定目录，等价于受控的 ctx.fs 外延；
search：接搜索类后端，让模型具备实时检索能力。

注册后同样用第 12 讲的 --dump-tool-catalog 验证：MCP server 暴露的工具应以 mcp/<server>/ 前缀出现在清单里。

四、MCP 工具与原生工具的 schema 差异

接入后你多半会遇到"描述对不上"的问题，根源在 schema 差异：

维度	原生工具	MCP 工具
来源	你写的 TS 函数	外部进程通过协议暴露
描述质量	你可控	取决于 server 作者
把关	可挂 guard	多走 approval 兜底
失败归因	本地堆栈	需看 server 进程日志

注意：MCP 工具描述往往较粗糙，模型可能"不敢调"或"调错参数"。必要时在 patch 里给它补一段更清晰的中文描述；外部 server 进程崩了，模型侧只看到超时，要回去看 server 的 stderr。

五、动手练习：让模型成功调用一个 MCP 外部工具

任选一个官方 MCP server（filesystem 最稳），按上面 patch 注册，然后给模型一个明确任务：

# 先确认工具已进清单
npx @deepseek-ai/dsh --profile web --dump-tool-catalog | grep mcp

# 然后让模型用 MCP 工具完成一次真实操作
npx @deepseek-ai/dsh web
# 消息框：用 filesystem 工具读取 /data 下的 README，并总结第一段。

看到模型调用了 mcp/filesystem/... 并拿到结果，本讲产出即达成。

六、常见坑

server 起不来：stdio 模式依赖 npx 能拉到对应包，先手动跑一遍命令确认环境；
工具没出现在清单：检查 scope 是否覆盖当前 profile，以及 server 握手是否超时；
调用超时无报错：多半是外部 server 进程崩了，去看它的 stderr，而非 dsh 本身；
描述太差导致不调：在 patch 给 MCP 工具补清晰中文描述，提升模型调用准确率。

七、官方文档对应章节

packages/mcp/mcp-client 的 README 与配置示例
docs/ 中 mcp、tool-catalog 相关章节
MCP 官方规范（modelcontextprotocol.io）了解协议本身

本讲内容基于 DeepSeek Harness 官方文档与项目源码整理，仅供学习参考，具体命令与配置请以官方最新版本为准。系列文章配合源码仓库食用效果更佳：https://github.com/deepseek-ai/deepseek-harness

咨询 DeepSeek Harness 相关问题，请加微信：A0qingfengyuan_01

个人观点，仅供参考，如有不对之处，请多包涵，欢迎指出。本文由 AI 协助完成！

DeepSeek Harness 教程 · 第13讲 MCP 接入