DeepSeek Harness的MCP应用教程

MCP 是扩展 Agent 能力的主要方式：接入一个 MCP 服务器，Agent 就能获得一整套现成的外部工具。DeepSeek Harness（命令名 dsh，简称 DSH）内置了 MCP 客户端桥插件，配置即可接入社区海量 MCP 服务。接入通过官方插件 @deepseek-ai/dsh-mcp-client 完成，支持 stdio 与 streamable-http 两种传输方式，配置写入 cordis.patch.yml 保存后热更新生效，工具命名形态与 Claude Code、Codex 保持一致。本教程以实战为主线，介绍在 dsh 中接入现成 MCP 服务、接入自定义 MCP 服务的完整流程，给出从 Claude Code、Codex 迁移配置的对照方法，并介绍使用 a4api 桌面工具可视化管理 dsh MCP 服务器的进阶方案。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

• MCP概念详解与应用完整教程，MCP 的概念、工作原理与传输机制本教程不再展开，请先通过该教程建立基础认知。
• DeepSeek Harness 安装与使用教程，你需要先完成 dsh 的安装并配置好模型 API Key。
• DeepSeek Harness插件概念详解与安装教程，dsh 通过 cordis.patch.yml 配置层挂载插件，本教程直接使用这一机制。
• Node.js和Npm安装与使用教程，本教程的 MCP 示例服务通过 npm 拉起。
• 一键切换DeepSeek Harness等Agent模型服务API 教程，第 5 章使用 a4api 桌面工具的可视化管理能力，需先完成 a4api 的安装。

资源下载

• a4api 发行版（Release）下载地址，提供最新版安装包 a4api-setup-<版本>.exe 与 SHA256 校验值，建议优先从此下载。
• a4api 应用网盘下载地址，提供安装包 a4api-setup-0.2.2.exe（夸克网盘分享），网络环境不佳、GitHub 下载过慢时的备用渠道。

1. dsh 接入 MCP 的方式

1.1 MCP 客户端桥插件

dsh 采用一切皆插件的架构，MCP 能力同样来自插件：官方插件 @deepseek-ai/dsh-mcp-client 充当 MCP 客户端桥，负责连接外部 MCP 服务器，并把服务器提供的工具注册为 Agent 可用的原生工具。

每接入一个 MCP 服务器，就在配置文件中添加一个该插件的实例。实例的配置项如下：

1.2 配置文件位置与生效方式

配置写在 profile 目录下的 cordis.patch.yml 中（Windows 下默认位于 C:\Users\<用户名>\.dsh\profiles\web\cordis.patch.yml），也可以写入主目录下的 C:\Users\<用户名>\.dsh\cordis.patch.yml 对所有 profile 生效。

dsh 支持配置热更新：编辑保存后，MCP 连接会自动断开并重建，通常无需重启 dsh web。

1.3 工具命名规则

接入后，模型看到的工具名为 mcp__<serverName>__<工具名>，例如 serverName 为 web 的服务器提供的 search 工具，在 Agent 侧的名称为 mcp__web__search。这一命名形态与 Claude Code、Codex 一致，来自不同服务器的同名工具通过命名空间隔离，互不冲突。

2. 接入现成 MCP 服务：open-WebSearch 实战

open-WebSearch 是一个开源的联网搜索 MCP 服务，支持多种搜索引擎，你可以访问Github仓库了解更多信息。本节通过它演示 stdio 方式的完整接入流程。

2.1 编写配置

编辑 C:\Users\<用户名>\.dsh\profiles\web\cordis.patch.yml，追加以下内容：

- insert:
    - id: mcp-open-websearch
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: web
        transport: stdio
        command: npx
        args:
          - '-y'
          - 'open-websearch@latest'
        env:
          MODE: stdio

配置说明：

• id：插件实例在配置树中的唯一标识，可自定义
• name：固定为 @deepseek-ai/dsh-mcp-client，即 MCP 客户端桥插件
• serverName: web：命名空间，Agent 看到的工具名形如 mcp__web__search
• transport: stdio：以子进程方式拉起服务，由 dsh 自动启动和管理，无需手动另开终端
• command / args：通过 npx -y open-websearch@latest 拉起服务
• env：open-websearch 通过环境变量 MODE=stdio 进入标准输入输出模式

2.2 验证配置

执行以下命令，可在不启动 Web 界面的情况下查看组合后的完整配置树：

dsh --profile web --dump-config

在输出中能检索到 mcp-open-websearch 条目，说明配置已正确叠加进配置树：

- id: mcp-open-websearch
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: web
    transport: stdio
    command: npx
    args:
      - '-y'
      - 'open-websearch@latest'
    env:
      MODE: stdio

2.3 对话验证工具调用

打开 dsh Web 界面（默认 http://127.0.0.1:3080），在对话框中输入：

请使用联网搜索MCP工具搜索：DeepSeek Harness GitHub 仓库地址是什么？只回答仓库地址。

Agent 判断需要联网后，会自动调用 mcp__web__search 工具执行搜索，并把结果整合进回答，对话流中可以看到完整的工具调用记录：

3. 接入自定义 MCP 服务：FastMCP 实战

除了社区现成的服务，你也可以接入自己编写的 MCP 服务器。服务器的开发方法在MCP概念详解与应用完整教程中已完整讲解，本节聚焦接入环节。

需要特别注意的是：dsh 的 MCP 客户端桥支持 stdio 与 streamable-http 两种传输，不支持早期教程常见的 SSE 模式。如果你按照MCP概念详解与应用完整教程的示例用 transport="sse" 启动了 FastMCP，只需把这一处改为 transport="http"，即可切换为 Streamable HTTP 模式：

from fastmcp import FastMCP

# 创建 MCP 服务器
mcp = FastMCP("my-fastmcp-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """计算两个数的和"""
    return a + b

@mcp.tool()
def sub(a: int, b: int) -> int:
    """计算两个数的差"""
    return a - b

if __name__ == "__main__":
    # streamable-http 模式，MCP 协议端点为 http://127.0.0.1:8001/mcp
    mcp.run(transport="http", host="127.0.0.1", port=8001)

启动服务并保持运行：

python server.py

终端中显示类似以下内容表示服务启动成功：

INFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit)
INFO:     Application startup complete.

3.1 在 dsh 中注册自定义服务

编辑 C:\Users\<用户名>\.dsh\profiles\web\cordis.patch.yml，追加以下内容：

- insert:
    - id: mcp-fastmcp-calc
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: calc
        transport: streamable-http
        url: http://127.0.0.1:8001/mcp

与 stdio 方式不同，streamable-http 只需提供 url，服务进程由我们自己维护，dsh 通过 HTTP 连接它。

3.2 对话验证工具调用

保持 FastMCP 服务运行，在 dsh 对话框中输入：

使用MCP计算工具计算 456789+654897 等于多少？只回答算式和结果。

Agent 会自动匹配到 mcp__calc__add 工具并传入参数 {"a":456789,"b":654897}，最终返回计算结果：

4. 从 Claude Code 与 Codex 迁移 MCP 配置

同一个 MCP 服务器可以在不同客户端之间复用。如果你已经在 Claude Code 或 Codex 中配置过 MCP，迁移到 dsh 只需做一次字段转换。

4.1 字段对照

4.2 Claude Code 配置对照示例

Claude Code 通过命令注册 MCP 服务器：

# stdio 类型
claude mcp add my-server -- npx -y open-websearch@latest

# streamable-http 类型
claude mcp add --transport http my-fastmcp-server http://127.0.0.1:8001/mcp

同样的两个服务迁移到 dsh 时，改写为第 2、3 节中的 YAML 配置即可。在 Claude Code 会话中输入 /mcp 可查看连接状态，对应 dsh 中的对话工具调用记录。

4.3 Codex 配置对照示例

Codex 通过 codex mcp 命令或直接编辑 ~/.codex/config.toml 配置：

# stdio 类型
codex mcp add my-server -- npx -y open-websearch@latest

# streamable-http 类型
codex mcp add my-fastmcp-server --url http://127.0.0.1:8001/mcp

对应的 config.toml 片段如下：

[mcp_servers.my-server]
command = "npx"
args = ["-y", "open-websearch@latest"]

[mcp_servers.my-fastmcp-server]
url = "http://127.0.0.1:8001/mcp"

5. 使用 a4api 可视化管理 MCP 服务器

前几章演示的都是手动编辑 cordis.patch.yml。当 MCP 服务器逐渐增多、配置又要在多个 Agent 之间复用时，纯手工维护容易出错。一键切换DeepSeek Harness等Agent模型服务API 教程介绍的开源桌面工具 a4api 自 0.2.2 起内置「MCP 管理」页签，把 Claude Code、Codex、dsh、ZCode 四端配置文件里的 MCP 服务器统一管理起来：自动发现聚合、可视化跨端迁移、快照回收站恢复，全程无需打开配置文件。

5.1 安装 a4api 并找到 MCP 管理

a4api 是 Windows 桌面应用（FastAPI + LayUI + pywebview），安装包见本文资源下载区块；安装与启动方式见一键切换DeepSeek Harness等Agent模型服务API 教程：下载安装包按向导安装即可，无需 Python 环境。启动后在窗口页签区可以看到「MCP 管理」页（0.2.2 起新增）。

默认情况下，a4api 管理的 dsh MCP 配置文件与本教程前面章节完全一致，即 profile 目录下的 cordis.patch.yml，profile 默认为 web：

dsh 的 MCP 服务器就是 @deepseek-ai/dsh-mcp-client 插件实例的 insert 条目，与第 2、3 节手动接入时写出的结构完全一致；dsh 没有项目级 MCP，服务器只存在于全局 profile 层。

5.2 发现与聚合：一张卡片看清四端服务器

进入「MCP 管理」页后，a4api 自动扫描四端的全局与项目级配置文件，把服务器归一为统一视图（name / transport / command / args / env / url / headers / cwd），并按服务器名聚合：同一服务器在多端重复出现时合并为一张卡片，标注「已在 N 端存在」。例如第 2 节接入的 web 服务器如果同时在 Claude Code 与 dsh 中配置过，就会显示为一张卡片并标注两处来源。

传输类型统一归一为 stdio / sse / http 三种（dsh 的 streamable-http 归为 http，ZCode 省略 type 时按字段推断）。卡片详情的 env / headers 只回显键名，不返回任何明文密钥。

a4api 只读写配置文件本身，修改 dsh 的 cordis.patch.yml 后仍由 dsh 的 watcher 热加载，无需手动重启 dsh web。

5.3 跨端迁移：把其它端的服务器迁到 dsh

第 4 章我们手动把 Claude Code / Codex 的 MCP 配置改写成 dsh 格式；使用 a4api 则可在卡片上直接选择「迁移」，把服务器配置片段复制到 dsh，并自动完成字段转换与传输类型改写：

迁移遵循以下规则：

• 源端保留：迁移是复制而非移动，源配置文件保持不变。
• 传输能力矩阵校验：迁移按源服务器的传输类型校验目标端是否支持，不兼容的组合整对失败并写入日志，绝不静默降级。四端支持情况如下：

可以看到，sse 传输的服务器无法迁入 dsh（dsh 只支持 stdio 与 streamable-http，与本教程第 3 节的说法一致）；归一为 http 的 streamable-http 服务器可以自由迁入 dsh，写入时自动还原为 transport: streamable-http 写法。同理，只有 stdio 的服务器能迁入 Codex。

• 先快照再写入：目标端已有同名服务器时，旧配置片段先快照进回收站再写入新内容，绝不静默覆盖；写入前自动备份目标配置文件（滚动保留 5 份）。
• dsh 写入细节：服务器写入 @deepseek-ai/dsh-mcp-client 插件实例下，重写时保留该实例的其他 insert 条目与其余插件；条目 id 按服务器名安全化（仅保留字母数字与 - / _）。
• 迁移日志：每次成功或失败的迁移都记入日志（时间、服务器、传输类型、源端、目标端、结果），可随时按新到旧查看，方便追溯。

5.4 回收站与安全

• 被替换或删除的服务器配置片段快照进回收站（数据目录 mcp_recycle\），30 天内可恢复原位或彻底删除，过期条目在访问时惰性清理。
• 回收站快照中的 env / headers 在落盘前经 Windows DPAPI 加密，恢复时才解密写回，保证“垃圾桶”里也没有明文密钥。
• 发现、预览、回收站相关接口对敏感字段全程脱敏，API 不回传明文。

6. 总结

6.1 核心内容回顾

• dsh 通过官方插件 @deepseek-ai/dsh-mcp-client 接入 MCP 服务器，一个服务器对应一个插件实例
• 配置写在 profile 或主目录的 cordis.patch.yml 中，支持热更新，dsh --profile web --dump-config 可验证配置树
• 工具以 mcp__<serverName>__<工具名> 形式注册，命名空间与 Claude Code、Codex 一致
• stdio 方式由 dsh 自动拉起本地服务，streamable-http 方式连接自行维护的远程服务；dsh 不支持 SSE 模式，FastMCP 示例将 transport="sse" 改为 transport="http" 即可接入
• Claude Code 与 Codex 的 MCP 配置可按字段对照表快速迁移到 dsh
• a4api 桌面工具自 0.2.2 起提供「MCP 管理」页签，统一管理 Claude Code、Codex、dsh、ZCode 四端的 MCP 服务器，dsh 侧直接读写 cordis.patch.yml 中 @deepseek-ai/dsh-mcp-client 插件的 insert 条目
• 使用 a4api 可自动发现聚合四端服务器、按传输能力矩阵校验后一键跨端迁移（源端保留、冲突先入回收站），被替换或删除的服务器 30 天内可恢复，密钥全程脱敏或 DPAPI 加密

6.2 常见问题与解答

问：配置了 MCP 服务器但对话中不调用？

按以下顺序排查：执行 dsh --profile web --dump-config，确认输出中包含你添加的插件条目；若配置树中没有，检查 cordis.patch.yml 的缩进与 YAML 语法；若配置树中存在但不调用，检查 serverName 是否与已有实例重复（重复会导致后加载的实例失败），以及 stdio 服务的 command 是否能在本机直接执行。修改配置后 dsh 会热更新连接，若仍未生效可重启 dsh web。

问：接入的 MCP 服务断线了怎么办？

MCP 客户端桥内置自动重连：连接丢失后按指数退避自动重试（默认最多 10 次），恢复后工具自动重新注册，无需人工干预。对自行维护的 streamable-http 服务，重新启动服务进程即可触发重连。

问：如何获取更多的 MCP 服务？

有很多 MCP 服务市场可供选择，比如 ModelScope MCP 广场、MCPHub、MCPMarket。这些服务市场提供了丰富的 MCP 服务，你可以根据需求选择合适的服务。

问：stdio 和 Streamable HTTP 应该选哪个？

本地工具选 stdio，由 dsh 自动拉起、零配置；团队共享或部署在远端的服务选 Streamable HTTP，通过网络访问并复用现有认证体系。

问：MCP 服务器多了以后，手动维护配置太麻烦怎么办？

答：可以使用 a4api 桌面工具的「MCP 管理」页签（0.2.2 起）可视化管理 dsh 的 MCP 服务器：自动发现四端服务器并聚合成卡片，一键把其它端（Claude Code、Codex、ZCode）的服务器迁移到 dsh（自动完成字段转换与传输能力校验），被替换或删除的服务器先进回收站，30 天内可恢复。安装与使用方式见一键切换DeepSeek Harness等Agent模型服务API 教程。