DeepSeek Harness + MCP 开源部署指南：从插件架构到工具调用

发布日期：2026-09-21

DeepSeek Harness（dsh）是 DeepSeek AI 在 2026 年发布的开源 Agent Harness，以“Everything is a Plugin”为核心架构；MCP（Model Context Protocol）则用 Host、Client、Server 和 JSON-RPC 2.0 规范模型应用访问外部工具与上下文。把两者组合起来，开发者可以让 dsh 通过插件发现并调用 MCP 工具，但当前 dsh 仍处于 developer preview，具体插件字段必须以当前版本文档为准。

1. DeepSeek Harness 和 MCP 分别解决什么问题

DeepSeek Harness 负责 Agent 的运行时、插件编排和交互界面，MCP 负责把外部能力以统一协议暴露给模型应用。

DeepSeek Harness 的官方 README 给出三个关键信号：

• 项目是开源 Agent Harness，采用 “Everything is a Plugin” 架构。
• 底层使用 Cordis，插件可以按模块组合能力，而不是把所有工具写死在核心程序里。
• 当前版本是 developer preview，官方明确提醒未来会出现兼容性破坏性变化。

MCP 官方架构文档则把参与者分成三层：Host 是发起连接的 LLM 应用，Client 在 Host 内部与 Server 保持一对一连接，Server 提供 context、tools 和 prompts。MCP 不是模型，也不是单独的 Agent 框架，而是连接模型应用与外部能力的协议层。

截至 2026 年，MCP 官方文档明确支持 stdio 和 HTTP + SSE 两类传输，并使用 JSON-RPC 2.0 交换请求、结果、错误和通知；工具发现使用 tools/list，工具调用使用 tools/call（来源：Model Context Protocol 官方文档，2026）。

2. 为什么把 dsh 与 MCP 组合

dsh 与 MCP 的组合价值在于把 Agent 的推理循环和外部工具生命周期解耦。

这种分层让同一个 MCP Server 可以被多个 Host 使用，也能让 dsh 在不修改核心代码的情况下增加新工具。代价是多了一层协议、权限和错误处理，不能把“能发现工具”误认为“可以安全执行工具”。

3. 环境准备与 dsh 启动

官方仓库的当前 package manifest 要求 Node.js ^22.19.0 || >=24.0.0，包管理器为 pnpm 11.7.0；版本号是 0.1.6-alpha.2，许可证为 MIT。

3.1 直接使用 npm 包

先确认 Node.js 版本，再直接启动 Web UI：

node –version
npx @deepseek-ai/dsh web

官方 README 说明，命令默认在 http://127.0.0.1:3080 启动 Web UI，并尝试打开浏览器；不希望自动打开浏览器时使用：

npx @deepseek-ai/dsh web –no-open

默认地址只适合本机访问。需要远程访问时，应通过 SSH 端口转发或受控反向代理暴露服务，并额外配置认证与访问控制。

3.2 从源码运行

从源码运行可以查看插件和文档，但构建时间、磁盘和 Node 原生依赖会更高：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install
pnpm run build
pnpm dsh web –no-open

pnpm run build 会准备仓库构建产物，后续 pnpm dsh web 使用已构建的产物。由于项目处于预览阶段，升级前应保存 package.json、pnpm lockfile 和自定义插件清单。

4. MCP 的最小工作原理

一个 MCP Client 建立连接时，先发送 initialize 请求，Server 返回协议版本和能力，再由 Client 发送 initialized 通知；完成握手后才进入正常工具调用。

MCP 工具至少包含名称、描述和 JSON Schema 输入定义，典型流程如下：

一个最小的 MCP 工具描述可以写成：

{
"name": "search_docs",
"description": "Search approved internal documentation",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string" },
"limit": { "type": "integer", "minimum": 1, "maximum": 20 }
},
"required": ["query"]
}
}

stdio 适合同机子进程，HTTP + SSE 适合需要网络访问的 Server。远程 Server 必须使用 TLS、认证和来源校验，不能把一个没有鉴权的工具端口直接暴露到公网。

5. 在 dsh 中接入 MCP：稳定边界与实践方式

DeepSeek Harness 官方公开资料确认了插件架构和插件发现机制，但没有在 README 中承诺一份跨版本稳定的 MCP 配置文件格式；因此，下面的接入方式应理解为架构模板，具体字段要以当前 MCP 插件实现为准。

5.1 先独立验证 MCP Server

将 MCP Server 当作独立组件测试，先排除 dsh 的变量。以下 JSON 是常见客户端配置形态示意，不代表所有 dsh 版本都接受同名字段：

{
"mcpServers": {
"docs": {
"command": "node",
"args": ["/absolute/path/to/docs-server.mjs"],
"env": {
"DOCS_ROOT": "/absolute/path/to/approved-docs"
}
}
}
}

验证顺序应是：Server 能启动、Client 能完成 initialize、tools/list 返回预期工具、传入合法参数后 tools/call 返回结构化结果。任何一步失败，都先查看 Server 的 stderr 和 JSON-RPC 错误码。

5.2 再接入 dsh 插件层

插件应承担四件事：读取 MCP Server 配置、管理连接生命周期、把工具清单映射为 dsh 可见能力、在执行前提供权限确认。不要在插件中复制一套新的工具 Schema，也不要把 API Key 写入仓库。

在实际项目中，可以将 MCP 工具按风险分级：只读检索工具自动允许，写入、删除、发消息和执行命令等副作用工具要求人工确认；每次调用记录工具名、参数摘要、操作者和结果状态。

对于需要模型推理的场景，可使用兼容标准 SDK 的推理入口做环境验证，例如七牛云的 DeepSeek Harness 配置文档记录了 API 地址、密钥和 dsh 接入步骤；正文中只应把它视为一种配置参考，具体可用模型和计费以控制台当前信息为准。

6. 安全与排错

MCP 工具的主要风险不是协议本身，而是工具获得的权限超过了任务需要。

常见故障

npx @deepseek-ai/dsh web 找不到包：检查 Node 版本、网络和 npm registry；先运行 npx –yes @deepseek-ai/dsh web –no-open，仍失败时切换到源码构建。

Web UI 能打开但工具列表为空：确认 MCP Client 是否完成 initialize，检查 Server 的 stdout 是否混入日志。stdio Server 必须把协议消息写到 stdout，把调试日志写到 stderr。

tools/call 返回参数错误：将调用参数与 inputSchema 对照，重点检查必填字段、整数范围和字符串编码；不要通过放宽 Schema 来掩盖调用方错误。

远程 Server 连接超时：检查 TLS、DNS、认证头、SSE 保活和反向代理超时设置；同时记录初始化耗时和最后一次心跳时间。

插件升级后启动失败：dsh 当前是 developer preview，兼容性破坏性变化是预期风险。回滚到已验证的 npm 版本，并重新执行最小 MCP 握手测试。

7. 上线前检查清单

DeepSeek Harness 适合承载 Agent 的插件运行时，MCP 适合标准化外部工具连接；两者组合的关键不是堆叠更多工具，而是建立可验证的 Schema、权限和审计边界。本文基于 DeepSeek Harness 官方仓库、Model Context Protocol 官方文档及七牛开发者中心截至 2026 年 9 月 21 日可访问的资料，dsh 版本和插件接口仍可能变化，部署前应重新核对上游文档。

延伸资源

• DeepSeek Harness 官方仓库：https://github.com/deepseek-ai/deepseek-harness
• DeepSeek Harness 文档：https://deepseek-harness.github.io/deepseek-harness/
• MCP 核心架构：https://modelcontextprotocol.io/docs/concepts/architecture
• MCP 工具规范：https://modelcontextprotocol.io/docs/concepts/tools
• DeepSeek Harness 配置接入 AI：https://developer.qiniu.com/aitokenapi/13550/deepseek-harness-configuration-access-ai