2026 DeepSeek Harness MCP 接入指南

截至 2026 年 8 月 18 日，DeepSeek Harness 官方仓库的 MCP 客户端桥接已经能把外部 Server 的工具注册到 Harness 的 ctx.tools，但项目仍处于开发者预览阶段，官方明确提醒会出现兼容性破坏变更。最快的做法不是一次接入多个工具，而是先用单个只读 MCP Server验证连接、工具发现和权限链路，再逐步开放写入能力。(github.com)

这篇文章适合三类人：需要把现有 MCP Server 接入 DeepSeek Harness 的 Agent 开发者；负责工具权限、密钥和日志的平台工程师；准备在云端 Mac 上持续运行 MCP 工具链的运维人员。

最后更新于 2026 年 8 月 18 日，配置与行为核实自 DeepSeek Harness 官方仓库、官方 MCP 客户端包说明及 MCP 传输规范。

第 1 阶段：先固定工具边界和验收任务

不要先从“能不能让 Agent 执行命令”开始。把准备接入的工具分成三层：

• ✅ 只读查询：代码检索、文件读取、数据库查询、网页抓取。
• ⚠️ 受控写入：创建工单、修改数据库记录、提交代码、写入文件。
• ❌ 可执行命令：Shell、部署、删除、重启服务或访问高权限系统。

第一次测试只允许第一层。你需要提前写好一条最小任务，例如“查询指定目录中的一个函数，并返回文件路径、函数名和一段脱敏摘要”。成功证据不能只写“Agent 回复正常”，而应至少包含：

1. MCP 进程启动日志；
2. 初始化与 tools/list 成功记录；
3. Harness 中出现对应的服务器限定工具名；
4. 一份可复核的任务产物。

官方桥接包会把工具注册成 mcp__<serverName>__<rawName> 的形式，并要求每个 MCP Server 使用唯一的 serverName。这意味着工具名称不是随意填写的显示名，而是后续排错、审计和多 Server 共存的命名空间。([github.com](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client))

第 2 阶段：选择传输方式并只接入一个 Server

DeepSeek Harness MCP 接入目前应优先在两种标准传输之间做选择：

<

传输方式	进程责任	适合场景	主要风险
stdio	Harness 启动 MCP 子进程	本地代码检索、单机数据库、开发调试	工作目录、环境变量和子进程退出状态容易被忽略
streamable-http	MCP Server 独立运行	远程 Mac、团队共用、集中运维	网络认证、Origin 校验、端点暴露和连接恢复更复杂

MCP 官方规范将 stdio 定义为客户端启动子进程、通过标准输入输出交换 JSON-RPC 消息；streamable-http 则通过单一 MCP 端点承载请求。远程场景不要因为“能访问 URL”就默认可以公开 MCP 端口，服务端仍需认证，并在本地绑定时优先限制到回环地址。([modelcontextprotocol.io](https://modelcontextprotocol.io/specification/draft/basic/transports))

官方示例的配置归属是 Harness 的 cordis.yml，而不是 DeepSeek 模型 API 的请求体。单个 stdio Server 可以按下面的结构准备，命令、参数和环境变量替换成你自己的 MCP Server：

- id: mcp-code
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: code
    transport: stdio
    command: npx
    args: ['-y', '你的只读 MCP Server 包名']
    env:
      CODE_TOKEN: !!js process.env.CODE_TOKEN
    cwd: /绝对路径/项目目录
    toolCallTimeoutMs: 60000
    failOnStartupError: true

这里的 60000 是官方桥接包文档列出的工具调用超时默认值；failOnStartupError 默认是 false，但首次接入建议临时改成 true，这样连接或工具同步失败时会直接暴露，而不是悄悄以“没有工具”的状态继续运行。(github.com)

连接阶段的成功信号与回退动作

按下面顺序执行，不要同时升级 Node.js、替换配置格式、增加第二个 MCP Server：

1. 固定 DeepSeek Harness、MCP 客户端包和 MCP Server 的版本。
2. 记录启动目录、启动用户、命令行参数和环境变量名称，密钥值只记录变量名。
3. 启动 Harness，确认 MCP 子进程确实被拉起。
4. 查看初始化和 tools/list 日志，确认工具列表返回。
5. 在 Agent 中调用一个无副作用查询工具。
6. 保存脱敏日志、工具名称、参数和任务产物。
7. 如果失败，先删除 MCP 配置，确认无 MCP 的基础 Harness 仍能运行，再单独修复连接问题。

官方实现会在连接后等待 listTools()，然后再把工具注册到 ctx.tools；如果发现失败且 failOnStartupError 为 false，插件仍可能激活，但模型看不到任何外部工具。([github.com](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client))

第 3 阶段：把“工具出现”与“工具可用”分开验收

MCP 工具出现在列表里，只能证明发现链路完成，不能证明 Agent 能正确调用。你还需要检查四件事：

• 名称：模型看到的是 mcp__code__search 一类的限定名，线上日志里仍应能映射回原始 MCP 工具名。
• 参数：确认必填字段、枚举值、路径格式和空值行为，没有把自然语言直接当成未经校验的命令参数。
• 返回值：检查文本、结构化 JSON、资源链接和错误标记是否被正确保留。
• 超时：查询任务的超时应能区分“Server 处理慢”和“传输已经断开”，不要统一显示成“Agent 失败”。

官方桥接包会监听 notifications/tools/list_changed，工具列表变化时重新同步；重新同步会替换原来的工具生成，而不是不断叠加。连接中断期间，最后一次成功发现的工具可能仍显示，但调用会失败；达到默认 **10 次**连续重连失败后，工具会被注销并停止自动重连。([github.com](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client))

因此，故障日志至少要分成三类：

1. MCP Server 错误：进程启动失败、依赖缺失、凭据无效、工具内部返回 isError。
2. 传输错误：stdio 子进程退出、HTTP 端点不可达、认证头缺失、网络中断。
3. Harness 注册错误：serverName 重复、工具名冲突、返回的工具列表非法或 Schema 不兼容。

不要把这三类错误都归结为“DeepSeek 模型不会用工具”。模型 API 和 MCP Server 是两条不同链路：前者负责推理请求，后者负责工具发现与执行。

第 4 阶段：增加凭据、写入工具和人工确认

凭据、连接配置和业务权限要分开管理：

<

内容	应放在哪里	不应怎么做
MCP Server 启动命令	cordis.yml 或部署清单	不要依赖个人终端历史
密钥值	环境变量、凭据引用或密钥系统	不要写进仓库、截图和日志
工具权限	Server 端账户、目标范围和审批策略	不要只依赖模型提示词
运行日志	受控日志目录或集中日志系统	不要记录完整 Authorization 头

写入型工具至少要绑定三个条件：目标范围、审批动作、回滚方案。例如数据库写入必须限制到测试库或指定表；创建资源前要求人工确认；任务产物中保存变更前后的摘要，而不是只保留“执行成功”。

远程 Mac 上尤其不要把密钥直接写进启动脚本。建议使用专用运行用户、最小文件权限和进程级环境变量；当任务来自外部输入时，再加一层人工确认与结果校验。对于浏览器、数据库和内部 API，网络出口也应按业务需要收紧，而不是为了方便把所有端口开放到公网。

第 5 阶段：迁移到云端 Mac，重新划分进程责任

本地电脑上的临时终端习惯，不能直接复制到云端 Mac。你需要明确三类进程分别由谁启动、监控和重启：

• DeepSeek Harness：负责 Agent 会话、插件加载和工具注册。
• MCP Server：负责外部系统适配、凭据使用和工具执行。
• 依赖进程：例如浏览器、数据库代理、代码索引器或本地运行时。

如果只通过 SSH 启动，然后关闭终端，进程可能退出；如果依赖图形会话，断开远程桌面后也可能出现工具可见但实际调用失败。远程验收应包括：

1. 启动 Harness 与单个 MCP Server；
2. 执行一次只读基准任务；
3. 断开 SSH 或远程桌面连接；
4. 检查三个进程是否仍在运行；
5. 重新连接后确认工作目录、环境变量和凭据引用未变化；
6. 人为停止 MCP Server，观察自动重连和工具重新发现；
7. 达到重连上限后，确认告警、工具注销和人工恢复路径。

官方文档列出的自动重连参数包括 reconnect.enabled、初始延迟、最大延迟和最大尝试次数；默认初始延迟为 **500 ms**、最大延迟为 **30000 ms**、连续失败上限为 **10 次**。这些是桥接包当前文档中的默认行为，不应被当成你所有版本都永久不变的保证。([github.com](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client))

第 6 阶段：用基准任务完成交付和回退

最后不要只测试“工具列表是否出现”，而要运行一条端到端任务：

发现代码检索工具 → 查询指定函数 → 返回结构化结果 → Agent 解释结果 → 如需写入则暂停并等待审批。

按下面条件判定：

• ✅ 通过：工具发现、调用、返回解析、日志记录和断线恢复全部成功。
• ⚠️ 有限通过：只读调用成功，但远程重启、写入审批或异常告警仍未完成。
• ❌ 不通过：工具未注册、参数被错误解释、密钥进入日志，或移除 MCP 后基础 Harness 无法恢复。

<

验收项目	通过证据	不通过时回退
进程启动	记录 PID、启动目录和版本	恢复无 MCP 配置
工具发现	出现限定名称并有 tools/list 记录	检查 serverName 与启动错误
只读调用	参数、返回值和产物可复核	更换为最小查询任务
断线恢复	重连后工具名称与 Schema 一致	关闭自动重连，改人工恢复
写入审批	有审批记录、目标范围和回滚证据	禁用写入工具
升级复测	版本变更后重新跑基准任务	固定旧版本并登记差异

多个 MCP Server 不必强行放进同一个运行环境。只有当它们的凭据、网络区域、运行用户和重启责任一致时，才适合共置；否则应拆分，避免一个浏览器工具故障拖累数据库工具，也避免一个高权限密钥进入所有 Agent 会话。 <

运行方案	推荐条件	评分	结论
本地单 Server	只读验证、开发调试、短任务	4.5 / 5	首次接入优先
本地多 Server	权限一致、依赖少、由同一人维护	3.5 / 5	验证通过后再采用
云端 Mac 独立环境	持续运行、团队共用、需要断线恢复	4.5 / 5	生产验证更合适
多台远程环境拆分	凭据、网络或风险等级不同	4 / 5	运维责任更清晰

如果你还没有稳定的远程承载环境，可以先参考 [MACGPU 的 Mac 远程运行入口](https://macgpu.com/zh/index.html)，再根据项目所在区域查看 [M4 Mac 远程环境方案](https://macgpu.com/zh/m4-dinggou.html)。这里的目的不是预设所有 MCP Server 都兼容，而是给通过本地最小测试后的工具链提供一个可重复的断线、重启和交付验收环境。

当前方案如果只是依赖个人 Mac，常见缺点是终端关闭后进程退出、密钥散落在本地配置、工作目录难以复现；如果直接放在普通云主机上，又可能遇到浏览器依赖、图形会话和 macOS 工具链不一致的问题。完成单个 MCP Server 的本地验证后，租赁 MACGPU 的云端 Mac 来做持续运行测试，通常比临时改造个人电脑更容易明确进程责任、恢复路径和交付边界；但如果你的任务长期满负载运行、必须接入专用物理接口，或需要永久保留本地硬件状态，自购设备仍可能更合适。