DSH 自带的 MCP 插件不支持 OAuth,这条链路上真正花时间的也不是写代码,而是插件加载体系的三层静默失败。 我用一个 stdio 代理把内网 MCP 接进来,最终注册出 33 个工具,中间踩了 10 个坑,每一个都是靠日志和 --dump-config 取证才定位的。
环境:DeepSeek Harness 0.2.2-rc.2(Electron 44.7.0 / 内置 Node 24.21.0)、本机 Node v22.12.0、app 自带的 pnpm 11.28.5、mcp-remote@0.16.6、MCP SDK @modelcontextprotocol/client@2.2.0。
目标是让 Agent 调用内网的日志与链路查询服务,并且登录走标准的动态 OAuth(PKCE + 动态客户端注册),而不是手工贴一个长期 token。
结论先行
| # | 现象 | 根因 | 修复 |
|---|---|---|---|
| 1 | MCP 配置里没有 OAuth/认证字段 | createTransport 只构造 stdio 与 streamable-http 两种传输,没有 authProvider 注入点 |
用 mcp-remote 做 stdio 代理,OAuth 交给它 |
| 2 | 直连 HTTPS 端点报 UNABLE_TO_VERIFY_LEAF_SIGNATURE |
内网 CA 不在 Node 的信任链里 | 在同一条内网链路上改走 http:// + --allow-http |
| 3 | 授权完成后连接不建立 | 回调地址用 localhost(可能解析成 ::1),本地监听却绑在 127.0.0.1 |
--host 127.0.0.1 --bind-host 127.0.0.1 |
| 4 | 配置里写 command: npx 起不来 |
app 进程的 PATH 只有系统目录,没有 node/npx | 用绝对路径的 node + proxy.js |
| 5 | 从 profile 里解析不到内置 MCP 插件包 | 插件条目的 name 按 profile 作用域解析,app.asar 里的内置包不在这个域里 |
用 app 自带的 pnpm 把插件及 peer 闭包装进 profile |
| 6 | 配置里加的新插件「没反应」,日志一片空白 | 顶层 - id: 只用于覆盖已有条目,id 不存在时整条被丢弃 |
新插件必须写成 - insert: [...] |
| 7 | 模块被 import 了,但 apply 永不执行 |
YAML 缩进少两格,config: 的子项成了同级,合成后是 config: null |
修正缩进,子项多缩两格 |
| 8 | 启动失败,提示插件在等 service | patch 引用的 hook 文件被外部工具重写时删掉 → ERR_MODULE_NOT_FOUND |
从安装包模板里拷回该文件 |
| 9 | 升级后 profile 里 rc.1 的插件「消失」 | 加载器做严格版本审计,不兼容的 bundle 整包跳过,只打一行 stderr | 把 profile 依赖对齐到同一版本 |
| 10 | 耗时对比数据不可信 | 测试脚本自己直连 MCP,绕过了 DSH 原生工具 | 删掉临时脚本,确认 mcp__ops__* 真出现在工具列表 |
能力边界:为什么不能直接用官方插件走 OAuth
看编译产物就够了(@deepseek-ai/dsh-mcp-client/lib/index.js):
function createTransport(config) {
switch (config.transport) {
case 'stdio': return new StdioClientTransport({
command, args, env, cwd })
case 'streamable-http':
return new StreamableHTTPClientTransport(new URL(config.url), {
requestInit: {
headers: config.headers } // 只有静态 header
})
}
}
- 配置 schema 里只有
url/headers(值可以是!!js表达式,比如Bearer ${process.env.MCP_TOKEN}),没有authProvider; - 而内置的 MCP SDK 本身是支持 OAuth 的(
OAuthClientProvider、UnauthorizedError、registration_endpoint都在); - 服务端也是标准实现:401 +
WWW-Authenticate: Bearer ... resource_metadata=...→ RFC 9728 保护资源元数据 → 元数据里带authorization_endpoint、token_endpoint、registration_endpoint(DCR),以及code_challenge_methods_supported: ["S256"]。
也就是说,缺口只在客户端插件的接线。要么改插件,要么在插件外面套一个「会 OAuth 的 stdio MCP 服务器」。选了后者:零代码,也不随 app 升级失效。这类「只在运行时才看得出问题」的组合层差异,和 配置层优先级 里讲的分层是同一套机制。
方案:把 OAuth 交给 stdio 代理

mcp-remote 负责全部 OAuth 细节:动态注册 → PKCE → 浏览器授权 → 换 token → 过期自动 refresh,token 落在 ~/.mcp-auth/mcp-remote-v1/<hash>_tokens.json。DSH 那边只看到一条最普通的 stdio MCP。
第一个坑:证书链
直连 HTTPS 端点报:
UNABLE_TO_VERIFY_LEAF_SIGNATURE
内网 CA 在系统钥匙串里有,Node 不认。三条路:注入 NODE_EXTRA_CA_CERTS、NODE_TLS_REJECT_UNAUTHORIZED=0(不可取)、或者在内网链路上直接走 http。选了第三条:
http://mcp-gateway.internal.example/mcp --transport http-only --allow-http
--allow-http 是 mcp-remote 的前置条件,默认拒绝明文端点。这个选择成立的前提是链路本身在内网,公网端点不要这么干。证书链的排查方式和 企业代理下的 TLS 证书错误 完全一致。
第二个坑:localhost 和 127.0.0.1 不是一回事
授权页点完「同意」,浏览器跳回 http://localhost:<port>/callback,但本地监听绑的是 127.0.0.1。有些环境里 localhost 先解析到 IPv6 的 ::1,连不上 → 页面看起来授权成功,连接却不建立。补两个参数后 3 秒走完:
--host 127.0.0.1 --bind-host 127.0.0.1
--host 影响生成的 redirect_uri,--bind-host 影响真实监听地址,两个都要。
第三个坑:宿主的 PATH 是极简的
DSH app 进程的 PATH 只有:
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
没有 node,没有 npx。而 mcp-remote 的 shim 是 #!/usr/bin/env node,所以 command: npx 一律失败。必须写绝对路径:
command: /Users/you/.n/bin/node
args:
- '/Users/you/.n/lib/node_modules/mcp-remote/dist/proxy.js'
插件加载体系的三层静默失败
这部分是整场排查里最贵的,也最值得写。

第一层:模块解析域
DSH 把插件树按 bundle → patch 分层合成后,每个条目的 name 在一个特定作用域里解析:
- 绝对路径:从 profile 目录出发,相对路径锚定在 patch 文件旁边;
- 包名:从 profile 的
node_modules解析,app.asar里的内置包不在这个域里。
所以内置的 @deepseek-ai/dsh-mcp-client 虽然 app 自己天天在用,从 patch 里引用它就是找不到。往 app.asar 里塞符号链接也不行(ESM realpath 校验会拒)。正确做法是装进 profile:
cd ~/.dsh/profiles/desktop
ELECTRON_RUN_AS_NODE=1 "/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness" \
".../runtime/primary-runtime/dependencies/pnpm/bin/pnpm.mjs" \
add @deepseek-ai/dsh-mcp-client@0.2.2-rc.2
注意要用 app 自带的 pnpm:它的版本要求 Node ≥ 22.13,本机 22.12.0 直接跑会报错,所以用 ELECTRON_RUN_AS_NODE=1 借 Electron 自带的 Node 24 来跑。装完还会依次报缺 dsh-scope → cordis → dsh-http-proxy → dsh-llm,一路把 peer 闭包补齐。手工装插件包的过程在 把本地插件装进 profile 里也有对照。
第二层:insert 还是 override
cordis.patch.yml 是补丁层,条目有两种语义。
裸 - id: 只覆盖已存在的条目。id 不存在时整条被丢弃,而且不会有任何报错——这是很容易踩的一格:
- id: mcp-ops-oauth
name: '@deepseek-ai/dsh-mcp-client'
新增插件必须放进 insert 列表:
- insert:
- id: mcp-ops-oauth
name: '@deepseek-ai/dsh-mcp-client'
config: {
...}
loader 的 failOnStartupError 默认是 false,所以丢弃是静默的。一开始照着已有的托管块改,却漏了这层 wrapper。
第三层:缩进,模块加载了但 apply 不跑
放进 insert 之后仍然没反应。给插件打临时埋点后看到:
[mcp] plugin module loaded ← 模块确实被 import 了
(没有 apply 那一行) ← 但 apply 从未执行
为了区分「条目没挂载」和「在等 service」,又加了一个形状相同的探针插件(同样 inject: ['tools'])。探针的 apply 能跑,说明条目挂载没问题、tools service 也在。
最后用 --dump-config 看合成后的树,问题一眼可见:
- id: mcp-ops-oauth
name: '@deepseek-ai/dsh-mcp-client'
config: null # ← 空的
serverName: ops # ← 配置项全跑到条目顶层了
transport: stdio
config: 在 6 空格,子项也在 6 空格,二者成了同级。schema 校验失败,cordis 不创建插件实例,于是只有 import、没有 apply。改成 8 空格后立刻 ready outcome=ok。
记住:
insert之后,config:及其子项相对- id:行要多缩进;args:是config的孙节点,还要再进一级。
启动失败不一定是 MCP 的锅
改完配置重启,应用起不来,界面提示若干插件「waiting for services」。crash log(~/Library/Logs/DeepSeek Harness/crash-*.log)里真正的错误只有一个:
agent-hooks → ERR_MODULE_NOT_FOUND
~/.dsh/hooks/agent-stop-hook.mjs
当天有外部工具重写了这个钩子插件的托管块,却没把 hook 文件写回磁盘,而 patch 仍引用这个绝对路径 → 插件加载失败 → 启动流程卡住,其它插件看起来都在等 service。
这类「patch 引用绝对路径文件」的插件是软依赖:文件消失即启动崩,而且报错不会指向 patch 文件本身。「在等 service」这个提示本身的排查顺序,可以对照 插件一直等不到服务时先看什么。
另外两个操作层面的坑:
- 启动失败后
open -a不会重新拉起(主进程卡死),osascript quit会返回-128(被失败弹窗挡住); - 需要先
kill -TERM,不行再kill -9,然后再open -a。
升级之后插件被静默跳过
app 自动从 0.2.2-rc.1 升到 0.2.2-rc.2,而 profile 里装的还是 rc.1。加载器做严格版本审计,不兼容的 bundle 整包跳过,只在 stderr 打一行:
dsh: skipping profile bundle "@deepseek-ai/dsh-subagent-codex": Error: Plugin
...@0.2.2-rc.1 is incompatible with dsh 0.2.2-rc.2 ...
而 app 正常启动时这行 stderr 是看不到的——表现为「codex / claude-code 子代理功能莫名其妙没了」。把两个 subagent 包升到 rc.2,重跑 --dump-config 后 stderr 干净。
规则:app 升级后,profile 里所有
@deepseek-ai/*依赖都要跟着对齐同一版本。
排查工具箱
--dump-config:看合成后的树
desktop profile 被 Electron app 独占,不能直接 dump,但可以复制一份再 dump:
mkdir -p /tmp/dshhome/profiles/test
cp ~/.dsh/profiles/desktop/{
cordis.yml,cordis.patch.yml,package.json,pnpm-lock.yaml} /tmp/dshhome/profiles/test/
ln -s ~/.dsh/profiles/desktop/node_modules /tmp/dshhome/profiles/test/node_modules
DSH_HOME=/tmp/dshhome ELECTRON_RUN_AS_NODE=1 \
"/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness" \
".../app.asar/dsh/node_modules/@deepseek-ai/dsh/lib/bin.js" \
--profile test --dump-config
它能同时回答三个问题:条目有没有进树、config 是否嵌套正确、哪个 bundle 被版本审计跳过了(看 stderr)。
Electron-as-Node 读 app.asar
普通 cat 读不了 asar,但 Electron 以 Node 模式运行时 fs 是支持 asar 的:
ELECTRON_RUN_AS_NODE=1 "/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness" -e '
const fs = require("fs")
const f = "/Applications/DeepSeek Harness.app/Contents/Resources/app.asar/dsh/node_modules/@deepseek-ai/dsh-mcp-client/lib/index.js"
console.log(fs.readFileSync(f, "utf8").slice(0, 2000))
'
插件源码、loader 实现、package.json 版本,全靠这个看。
分级探针
- 探针 A(
inject: []):证明 patch 的insert机制本身通不通; - 探针 B(
inject: ['tools'],和出问题的插件同形):证明依赖的 service 在不在、条目是否真的被挂载; - 埋点:在模块顶层、
apply入口、createTransport、connection.ready、syncTools各打一行到/tmp/*.log,并挂上uncaughtException/unhandledRejection。
注意 pnpm add 会覆盖手工埋点的文件,升级后埋点消失,别以为是「埋点没生效」。
其它
pgrep -fl "mcp-remote/dist/proxy.js":stdio 子进程有没有起来;~/Library/Logs/DeepSeek Harness/crash-*.log:启动失败的唯一可信现场;- 应用正常启动时 stderr 基本是空的,不要指望在这里看到插件错误。
验证时的两个方法论坑
- 工具数统计:第一版统计出 40 / 34 个工具,都是错的——把
serverInfo.name和 SSE 重复事件也算进去了。正确做法是只看tools/list的tools[]去重后的原始名称集合,两条链路(静态 token / OAuth)都是 33 个。 - 测试污染:在没有原生工具的那几轮里,自动化脚本自己找到了
~/.mcp-auth的 token,写了个直连 MCP 的脚本。结果是「看起来能查日志」,但走的是脚本而不是 DSH 工具,耗时对比数据也不可信。验证接入成功的唯一标准是mcp__ops__*出现在会话的工具列表里,不是脚本能调通。
最终配置
新插件必须放进 insert 列表:裸 - id: 只覆盖已存在的条目,id 不存在时会被静默丢弃(failOnStartupError 默认 false)。
- insert:
- id: mcp-ops-oauth
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: ops
transport: stdio
# 绝对路径:app 的 PATH 里没有 node/npx
command: /Users/you/.n/bin/node
args:
- '/Users/you/.n/lib/node_modules/mcp-remote/dist/proxy.js'
- 'http://mcp-gateway.internal.example/mcp'
- '--header'
- 'x-mcp-client-version: 1.0.0'
- '--transport'
- 'http-only'
- '--allow-http'
- '--host'
- '127.0.0.1'
toolCallTimeoutMs: 180000
验证日志(埋点期):
[mcp] apply serverName=ops
[mcp] createTransport {"transport":"stdio","command":"/Users/you/.n/bin/node",...}
[mcp] syncTools registering 33 tools: mcp__ops__ops-global-helper, mcp__ops__ops-log, ...
[mcp] ready outcome=ok
可复用的检查清单
给 DSH 新增一个「要自己启动子进程」的 MCP 插件时,按顺序过一遍:
name指向 app.asar 内置包吗?→ 先pnpm add进 profile,用 app 的 pnpm + Electron-as-Node。- 条目是新增的吗?→ 必须写
- insert:,不能裸- id:。 config:的子项比- id:多缩两格了吗?→ 用--dump-config确认不是config: null。- 子进程命令是绝对路径吗?→ app 的 PATH 只有系统目录。
- app 版本变了吗?→ profile 里
@deepseek-ai/*全部对齐同一版本,否则整包被跳过。 - 端点证书链不全?→ 注入
NODE_EXTRA_CA_CERTS,或在内网链路上走 http +--allow-http。 - 起不来先看 crash log,不要只看 UI 提示的「waiting for services」。
- 验证标准是工具列表里出现
mcp__<server>__*,不是脚本能直连。 - 临时探针和埋点用完即删(探针文件、patch 条目、
/tmp日志、源码里的调试分支)。
这类问题的共同点:失败都是静默的。 插件没被插入不报错,配置形状不对不报错,版本不兼容只打一行 stderr,启动失败只显示「在等 service」。所以真正可迁移的经验不是那 10 个坑本身,而是那三样取证工具——--dump-config、Electron-as-Node、分级探针。
相关阅读
- troubleshoot-tls-certificate-errors-with-a-corporate-proxy
- pending-plugins-missing-services-diagnostics
- config-layer-precedence
- install-a-local-plugin-checkout-into-a-profile
本文由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
完整版含两张示意图,见:DSH 接入内网 MCP:OAuth 代理与三层静默失败
文中引用的插件开发文档收录于:https://dsh-plugin.com/zh/blog