「工具列表里明明有这个 mcp__ 名字,怎么一调用就报错?」 这是接入 MCP 时常见的困惑。多数时候,问题出在一个误解上:把「工具名出现在列表里」当成了「连接处于健康状态」。
实际排查时,下面六种情况尤其容易被误判:
- 把工具出现在列表里当成实时健康检查;
- 拿 stdio 的排查思路去检查 HTTP 服务,或反过来;
- 以为传输连接成功就说明服务端准备工作已经完成;
- 认为命令执行成功,就说明密钥注入配置已经生效;
- 默认认为子进程一定遵循 DSH 的代理设置;
- 把部署差异当成协议差异。
先记住这一点:传输方式会影响进程归属、配置方式和网络排查路径,但不能决定服务器或工具是否可信。站内基础版可参考两种 MCP 连接方式有什么区别。
一、两种接入方式改变了什么
记忆 MCP 指南介绍了通用客户端行为:DSH 会解析选定的 Cordis overlay,启动配置好的 stdio 命令,或连接配置好的 Streamable HTTP URL;随后发现工具,并按 mcp__<serverName>__<tool> 的形式对外提供。
两种方式都能让智能体调用工具,但它们依赖的运行条件并不相同。
| 问题 | stdio | Streamable HTTP |
|---|---|---|
| 端点 | 配置的子进程命令 | 已运行服务的 URL |
| 生命周期 | 客户端随插件启动和停止子进程 | 上游服务独立运行 |
| 通用配置 | transport、command、args、env、cwd |
transport、url、headers |
| 首先排查 | 可执行文件、参数、环境和启动 | 服务可用性、端点、认证和网络路径 |
| 代理考虑 | 子进程继承其余环境,行为还取决于运行时 | 出站请求遵循文档中的代理规则 |
排查时,最值得先看的是「首先排查」这一行。失败时,如果拿 stdio 的检查清单去查 HTTP 服务,或反过来,就容易从错误的环节开始,导致排查越走越远。
还有一个前提需要先讲清楚:DSH 不负责下载服务器、初始化数据库、创建云账户,也不负责选择模型或 embedding 提供方。传输连接成功,不代表提供方要求的准备工作已经完成。后文还会回到这条边界。
二、stdio:从命令启动到工具发现
1. 通用配置示例
指南给出的最小可参考配置如下:
- insert:
- id: memory-my-server
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: my-memory
transport: stdio
command: my-memory-mcp
args: []
env: {
}
cwd: !!js process.cwd()
这段配置有三点需要注意:
- 其中的
command是用于示意的服务器可执行文件,DSH 不会自动安装它; id和serverName应该保持唯一,命令和参数则要填写实际提供方支持的内容;- 不能把某个提供方的路径或设置直接套用到另一个提供方,还要分别满足各自的安装与存储要求。
2. 环境变量过滤有明确范围
启动子进程前,桥接器会移除名称通常表示凭据的变量,以及所有 DSH_* 变量;环境中的其他变量仍会继承。
如果上游功能需要额外密钥,指南要求通过这一行配置中的 config.env 提供,而不是把密钥直接写进 YAML。
但过滤部分变量,并不等于子进程无法接触敏感信息。仍需核对服务器的实际要求和密钥管理方式。变量注入规则的具体说明,见怎么给 stdio MCP 服务器传必需的环境变量。
3. 工具发现是异步过程
应等提供方的 mcp__... 工具出现后,再判断连接是否失败。如果刚启动就断言「没有连上」,很容易把尚未完成的发现过程误当成故障。
指南还说明,子进程崩溃后会按退避方式自动重连,并重新同步工具。因此可能出现一个不太直观的情况:连接中断时,工具仍列在列表里,但调用会失败。
只有耗尽重连预算后,工具才会被注销;要恢复重连,需要重载或重启。因此,列表中仍有工具名称,不是实时健康检查的结果。
三、Streamable HTTP:排查重点转向服务和网络
1. 配置字段与信息来源都不同
连接远端服务器时,使用 transport: streamable-http、url 和 headers,不再使用 stdio 的那组字段。
端点和认证要求应以对应服务器的文档为准。指南没有给出通用 URL、header 或登录流程,因此不能凭空编造值让读者直接复制。
还要确认DSH 发起连接前,服务已经运行。这和 stdio 的方式不同:stdio 由 DSH 启动子进程,而这里连接的是一个独立服务,DSH 不负责监管它。
企业内网 OAuth 是另一个常见场景,认证链路的具体差异可参考内网 MCP 走 OAuth 怎么接。
2. 代理规则因连接路径而异
网络代理指南说明,DSH 会在启动时读取标准代理环境变量,并将其用于 HTTP MCP 等出站请求。
HTTP_PROXY/HTTPS_PROXY用于指定代理;NO_PROXY用于列出需要直连的主机;- loopback 始终绕过代理。
文档特别指出,NO_PROXY 中的 CIDR 网段不生效,应改用主机名或域名后缀。因此,把整个网段写进 NO_PROXY,实际可能一个目标也匹配不上。
这一差异在什么情况下容易造成误判?例如,浏览器能访问服务,但 DSH 进程使用的是另一套代理设置。此时,人工在浏览器里验证通过,并不能直接说明 DSH 也能连通。
3. 子进程是否使用代理要另行确认
stdio 的代理行为还要看子进程本身。网络指南说明,被启动的命令和 MCP 子进程会继承代理变量;不过,Node 子程序需要 Node 22.21 或更新版本才遵循这些变量,其他运行时的行为各不相同。
所以,要检查服务器自身的出站路径,不能假设它使用 DSH 的 HTTP 客户端。还要留意两点:代理 URL 可能包含子命令能够读取的凭据,应避免将其暴露在日志中。证书相关故障的排查见企业代理下的 TLS 证书错误怎么处理。
四、如何选择和验证
1. 按流程逐项确认
- 先确认提供方给出的是本地可执行文件、已运行的 Streamable HTTP 服务,还是两者都有,并阅读其安装、身份、认证和存储要求。
- 根据接入路径准备环境:stdio 要准备可执行文件,并配置命令、参数和必要环境;HTTP 要启动或确认服务正在运行,并向提供方获取 URL 和所需 header。
- 将客户端行加入合适的 overlay,并确保身份唯一。指南中的示例 overlay 需要主动启用;只安装服务器不会自动将它加入随附组合。
- 启动或重载组合,等待工具发现,再检查
mcp__<serverName>__<tool>名称和连接错误。 - 选择合适的操作进行测试,并检查实际结果,不要只确认工具名称已经出现。
2. 用实际操作验证整条链路
指南给出的记忆集成测试很有参考价值:写入唯一测试值 → 在同一 Host 中创建新的 DSH 会话 → 请它回忆该值 → 检查后续回答是否使用了该值。
这样的测试不只检查工具发现,还会检查写入、跨会话回忆和实际使用;同时,提供方的存储范围必须保持不变。
阅读这个示例时,要同时记住两条限制:它不意味着每个 MCP 服务器都提供记忆工具;其他服务器应选择不含敏感数据、且符合其能力的测试方式。
3. 区分工具未出现和调用失败
工具还没出现,和工具已经出现但调用失败,是两类不同情况,排查起点也不同:
- 工具尚未出现:先确认初始发现是否已经结束,再检查子进程是否无法启动、HTTP 服务是否不可达,或服务是否拒绝认证;
- 工具先前可用、现在调用失败:还要检查是否处于重连过程中。
记录问题时,写明传输方式、服务状态和脱敏后的错误,会比只写「工具不工作」更便于定位。工具命名规则见MCP 工具是怎么命名的。
4. 比较接入方式时核对部署条件
对比两种接入方式时,应使用同一提供方明确支持的能力,并分别记录服务运行位置、身份和存储范围。
这是因为切换传输方式时,认证方式和数据位置也可能随之改变。因此,某一次测试的结果不能自动证明另一条连接访问的是同一份数据。判断时应以提供方文档和实际结果为依据,避免把部署问题误认为协议本身的问题。
五、附:默认关闭的示例
指南中的三个记忆示例默认关闭,用途是提供互操作参考,并不代表背书。
此外,这些示例都使用 stdio。通用 HTTP 字段只说明如何连接其他远端服务器,不保证某个特定提供方支持这种传输方式。
想了解记忆接入的配置方式,可参考记忆 MCP 怎么配置。
六、限制与安全边界
- 传输方式不决定可信度:连接前应检查可执行文件或服务、其权限、数据保留方式与凭据。
- 工具列表、连接成功、一次测试成功,都不能证明安全,也不能保证服务持续可用。
- HTTP 服务由其运营者负责:DSH 不监管这个独立服务。
- stdio 环境过滤是有选择的:其余变量仍会继承,过滤并不意味着子进程接触不到敏感信息。
- HTTP header 与代理设置可能含密钥:共享示例不要放真实秘密,分享日志前先检查。
- 不支持 SOCKS 代理 URL:相关协议可能因此直连;网络路径有要求时应核实实际路由。
mcp__名称在重连期间仍可能列出:看到名字不等于连接健康。- 命令执行成功不等于凭据真的生效了:应确认提供方是否真的拿到了它需要的值。
- 示例默认关闭且不代表背书:不要因为「指南里有」就当成推荐配置。
七、术语速查
- stdio:通过配置的子进程和标准流通信的传输方式。
- Streamable HTTP:使用 URL 和 header 的远端连接类型。
- Overlay:把 MCP 客户端行加入组合的配置补丁。
- 发现:获取上游工具并暴露其 DSH 名称的过程。
NO_PROXY:文档中的代理配置直接访问的目标列表。- 重连预算:子进程崩溃后的有限重试额度。
相关阅读
- 两种 MCP 连接方式有什么区别
- 怎么给 stdio MCP 服务器传必需的环境变量
- 内网 MCP 走 OAuth 怎么接
- 企业代理下的 TLS 证书错误怎么处理
- MCP 工具是怎么命名的
- 更多 DSH 实践文章
本文依据 DeepSeek Harness 官方记忆 MCP 指南与网络代理指南整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
原文地址:https://dsh-plugin.com/zh/blog/stdio-and-streamable-http-mcp-connections-differ
插件与文档收录于:https://dsh-plugin.com/zh/blog