DSH MCP Manager 配置指南: OAuth、stdio 与工作区隔离

DeepSeek Harness 可以通过 MCP 调用搜索、数据库、文件系统和内部服务。真正麻烦的部分通常不是“连上一个服务器”，而是长期管理：哪些工具全局可见，哪些只属于一个项目；远程服务怎样做 OAuth；本地 stdio 进程怎样启动；工具太多时如何减少 schema 占用；凭据应该放在哪里。

dsh-mcp-manager 把这些问题放进 DSH Web UI 的“设置 → MCP”页面。它支持远程 Streamable HTTP、本地 stdio、OAuth、静态 Token、工作区隔离和可选的按需 broker。本文基于 hyqhyq3/dsh-mcp-manager 的 v0.6.0 仓库。该仓库的 host 与 client JavaScript 已通过 node --check，但仓库没有提供可直接运行的完整测试命令。因此，本文把“插件能加载、服务器能连接、工具能调用、工作区不可越界”列为安装后的四个硬验证项。

如果你只需要一个固定 MCP 服务器，而且愿意手写静态配置，DSH 内置的 @deepseek-ai/dsh-mcp-client 已经够用。这个管理插件的价值在于 OAuth、stdio、热更新和工作区隔离。不要为了多一个界面而增加组件。

安装前确认环境

仓库要求 DeepSeek Harness 的 Web profile、Node.js ^22.19 或 >=24，并要求 pnpm 在 PATH 中。Windows 下的 npx.cmd、uvx.cmd 等 shim 会通过 cmd.exe 启动。

先执行：

node --version
pnpm --version
dsh --profile web --dump-config

如果 DSH 是用 npx @deepseek-ai/dsh web 启动，系统里可能没有全局 dsh。后面的安装命令已经使用 npx -p @deepseek-ai/dsh dsh，不用先全局安装 CLI。

建议先备份 DSH 配置：

$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
$dshHome = Join-Path $HOME '.dsh'
$backup = Join-Path $HOME ".dsh-backup-$stamp"
Copy-Item $dshHome $backup -Recurse

如果你还没有理解 MCP 工具如何进入 Agent，可以先看 DeepSeek Harness MCP 与 Skill 开发指南、DSH 作为 MCP 子代理的实践 和 DeepSeek Harness 插件架构。

安装插件

使用仓库给出的安装命令：

npx -p @deepseek-ai/dsh dsh plugin --profile web add github:hyqhyq3/dsh-mcp-manager

安装后重启 Web profile，再刷新页面：

npx @deepseek-ai/dsh --profile web

具体启动命令以你的服务方式为准。重点是重启同一个 profile。插件包内带 dsh.bundle.patch，正常安装时不需要手改 cordis.patch.yml。

进入“设置 → MCP”。如果没有这个页签，先检查：

1. 插件是否装进 web profile。
2. 运行中的 Web UI 是否也是 web profile。
3. dsh --profile web --dump-config 是否包含 mcp-manager。
4. 浏览器是否仍显示旧的前端资源。

不要在页签没出现时先改 MCP 配置文件。插件本身还没加载，改服务器配置不会解决问题。

先接一个本地 stdio 服务器

stdio 是最适合做第一条验证的传输。它不需要远程网络和 OAuth，可以把问题限定在进程启动、JSON-RPC 和工具注册三层。

在“设置 → MCP”中点击“添加 MCP 服务器”，选择 stdio，填写：

• 名称：filesystem-lab
• 命令：npx
• 参数：每行一个参数
• 工作目录：一个专门的测试目录

参数示例：

-y
@modelcontextprotocol/server-filesystem
.

保存后，状态应从连接中变为“已连接（N 个工具）”。新建会话后，Agent 看到的工具名应以服务器名为前缀，例如：

mcp__filesystem_lab__read_file
mcp__filesystem_lab__list_directory

具体工具名由 MCP 服务器返回。服务器名称会经过安全归一化，不要依赖空格、标点或大小写制造不同命名。

stdio 的安全边界

stdio 服务器是本地常驻子进程。它的权限来自 DSH host 用户。文件系统 MCP 指向哪个目录，就可能读写哪个目录。测试时不要把根目录、用户主目录或包含密钥的目录作为工作区。

在 POSIX 环境，参数会按规则分词，不进行 shell 展开。Windows 则交给 cmd.exe，&、|、> 和 %VAR% 等字符会被解释。生产配置应使用明确命令和绝对路径，不要把不可信文本拼进命令行。

Agent 安全不是提示词问题。可以结合 AI Agent 最高权限风险、Agent 误赋全权限事故 和 MCP 安全护栏 Conduct 建立权限检查表。

配置远程 HTTP 与静态 Token

远程 MCP 选择 HTTP。基础字段包括服务器名称、URL、认证方式和请求头。

静态 Token 不应直接写入配置。先在启动 DSH 的环境中导出：

$env:MCP_BEARER_TOKEN = "your-token"

在插件界面只填写环境变量名 MCP_BEARER_TOKEN。插件把它记录为 tokenEnv，不会把值写进配置文件。

自定义请求头也应优先使用 headerEnv。只有非敏感的固定头才适合直接写进 headers。如果 DSH 是 systemd、LaunchAgent 或容器启动，交互终端里的环境变量不会自动进入服务进程。出现 401 时，先检查运行 DSH 的进程环境，而不是反复删除服务器。

OAuth 配置与回调检查

插件支持授权码流程、PKCE、动态客户端注册和 refresh token 轮换。添加 HTTP 服务器时选择 OAuth，保存后点击“去认证”。浏览器完成登录后，会回到类似下面的地址：

http://127.0.0.1:<port>/mcp-manager/callback/<id>

OAuth 提供方必须允许回环地址。如果提供方只接受固定公网 callback，这个流程不会成功。

认证成功后，工具会立即注册。重启 DSH 后插件会尝试自动重连。这里有一个重要边界：OAuth token 会明文保存在 ~/.dsh/mcp-manager.json。它没有写进项目仓库，但仍是敏感文件。应限制文件权限，不要把 .dsh 打包上传，也不要在截图和支持日志里暴露它。

静态 Token 和 OAuth Token 的存储方式不同：

• 静态 Token：只保存环境变量名，值不落盘。
• OAuth Token：保存在插件状态文件，用于重启后续期。
• 工作区 OAuth：Token 仍进全局状态文件，不写进项目的 mcp.json。

用工作区隔离 MCP

全局服务器会出现在所有工作区。数据库、仓库文件系统和内部 API 通常不应该全局暴露。把它们写进项目目录：

<workspace>/.dsh/dshmm/mcp.json

示例：

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "unity-mcp": {
      "type": "http",
      "url": "http://localhost:8090/",
      "authMode": "static",
      "tokenEnv": "UNITY_MCP_TOKEN"
    }
  },
  "exclude": ["github"]
}

这个配置做三件事：给当前工作区启动文件系统服务器，连接本地 Unity MCP，并隐藏一个名为 github 的全局服务器。工作区服务器的工具只注册进工作目录解析到该工作区的会话。

修改文件后会热更新。JSON 写坏时，界面会显示错误，并继续使用上一份有效配置。修好文件后再观察工具列表，不需要先重启整个 DSH。

服务器名在“全局 + 所有工作区”之间必须唯一。名字冲突时插件会跳过冲突项。不要给不同项目都取含义模糊的 tools、mcp 或 server。

什么时候开启按需 broker

默认模式会把所有 MCP 工具 schema 放进模型请求。服务器多、工具多时，提示词体积会上升，模型也更容易选错工具。

开启按需模式后，Agent 只看到三个 broker：

mcp_search_tools
mcp_describe_tool
mcp_execute_tool

推荐调用顺序：

1. mcp_search_tools 按任务查候选。
2. mcp_describe_tool 读取精确输入 schema。
3. mcp_execute_tool 执行目标工具。

这是一种 progressive disclosure。它适合挂了几十个 MCP 工具的 profile，不适合只有两三个工具的简单环境。按需模式目前只覆盖默认 native 工具呈现。使用 code 或 both 的 Agent 会保留完整目录，不能假设所有模式都减少了 schema。

按需开关对整个 profile 生效。打开后应在一个旧会话和一个新会话各验证一次。旧会话从下一次请求开始使用新设置，但它可能保留此前的工具上下文。

四步验收

1. 连接状态

UI 显示“已连接（N 个工具）”，不是“待认证”或“错误”。

2. 工具可见性

关闭 broker 时，确认出现 mcp__<server>__*。开启 broker 时，确认原始工具隐藏，只出现三个 broker。

3. 最小调用

先调用只读工具，例如列目录或查询状态。验证返回结果与目标服务器一致，再测试写操作。

4. 隔离验证

在工作区 A 添加专属服务器，然后新建工作区 B 会话。B 不应看到 A 的工具。只在 A 中隐藏的全局服务器，在 B 中仍应可见。

只验证“工具调用成功”还不够。隔离失败意味着插件功能可用，但安全边界失败。

常见问题

OAuth 登录后仍显示待认证

检查 callback 是否回到当前 GUI origin、提供方是否允许回环地址、系统时间是否准确。GUI 地址变化后，插件可能重新注册 OAuth 客户端。

stdio 服务器立即退出

在同一用户环境中直接运行命令，检查 Node、Python、npx 或 uvx 是否在 DSH host 的 PATH 中。Windows 要注意 .cmd shim 和命令行转义。

工具连接了但 Agent 看不到

检查工作区是否匹配、服务器是否被 exclude、名称是否冲突、当前是否开启 broker。开启 broker 后，隐藏工具不能被直接调用，必须通过 mcp_execute_tool。

tools/list 更新后工具没变化

插件会响应 notifications/tools/list_changed。如果服务器不发送通知，禁用后再启用服务器，迫使它重新读取工具列表。不要先删除 OAuth 配置。

该不该同时安装另一个 MCP Manager

不建议。站内此前记录过多个社区实现，包括 DSH MCP 管理面板 和 MCP 子代理桥接插件。同一 profile 装多个同名管理器，容易产生 loader、路由和工具命名冲突。先选一个实现，再做验收。

卸载与清理

先从 profile 移除插件：

npx -p @deepseek-ai/dsh dsh plugin --profile web remove dsh-mcp-manager

重启后确认“设置 → MCP”页签和管理器注册的工具消失。卸载插件不代表状态文件自动删除。若确定不再恢复，手工清理 ~/.dsh/mcp-manager.json 前先备份，并确认里面没有其他仍需保留的服务器注册信息。

工作区配置位于项目目录。是否删除应由项目决定。不要写一个全局脚本递归删除所有 .dsh/dshmm/mcp.json。

相关阅读

• DeepSeek Harness 插件目录
• DeepSeek Harness 插件市场
• DSH Agent Skill
• DeepSeek Harness Tavily 搜索插件
• DeepSeek Harness 浏览器自动化
• DeepSeek Harness 部署故障
• DeepSeek Provider 配置指南
• DeepSeek Harness 桌面版

一手资料

• dsh-mcp-manager GitHub 仓库
• DeepSeek Harness 官方仓库

dsh-mcp-manager 的高级用法不是“多连几个服务器”，而是把全局、工作区、凭据和工具目录分开管理。先用只读 stdio 服务器过完四步验收，再接 OAuth 和有写权限的内部工具，会少很多隐蔽风险。