这个故障在一端很安静,在另一端很吵。MCP 客户端连接成功,面板显示服务器在线,工具列表却是空的。服务器日志里只有一行干巴巴的 400,没有堆栈。
我们把博客的 MCP 接到 Verboo Code 时就遇到了这个情况。客户端说的是一个 MCP 协议版本,服务器要求的是另一个。两边都没有 bug:协议本身就允许版本协商失败,并且明确规定失败时每一端应该怎么做。
我们选的出路既不是 fork 客户端,也不是重写服务器,而是在中间放一座很小的本地桥。这篇文章说明它为什么有效,以及怎么搭你自己的。
为什么 MCP 协议版本会让连接直接断掉?
因为版本协商发生在第一条消息里,而且不是建议性的。客户端用自己支持的版本发 initialize,服务器用自己的版本回应,如果客户端不支持这个回应,正确的行为就是断开连接。
规范在这几点上写得很直接:
- 如果服务器支持请求的版本,它必须用同一个版本回应。否则它必须用自己支持的另一个版本回应,优先选最新的那个。
- 如果客户端不支持服务器返回的版本,它应该断开连接。
- 走 HTTP 时,客户端必须在
initialize之后的每个请求里带上MCP-Protocol-Version头,版本无效或不受支持时服务器必须返回400。
这种情况下出现的错误通常是下面这个,里面带着服务器接受的版本列表:
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32602,
"message": "Unsupported protocol version",
"data": {
"supported": ["2025-06-18"],
"requested": "2025-03-26"
}
}
}
记住 data.supported。桥在上游那一侧要用的就是这个版本。
怎么查每一端到底在哪个版本?
从握手看,不要猜。任何 MCP 会话的第一条消息都是 initialize,两个版本都会出现在里面。在怪客户端之前,先用一个 curl 看一眼:
curl -s https://your-server/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": { "name": "probe", "version": "0.0.0" }
}
}'
如果返回的 protocolVersion 和你发的不一样,说明服务器把它在用的版本告诉你了。如果响应里带了 Mcp-Session-Id 头,记下来:后面每一次调用都必须带它。
| 现象 | 可能原因 | 看哪里 |
|---|---|---|
| 服务器显示已连接,工具列表为空 | 客户端不支持握手返回的版本 | initialize 的响应和 -32602 错误 |
握手之后每个调用都 400 | MCP-Protocol-Version 头缺失或写错 | 客户端构造的 HTTP 请求 |
第一个 POST 就 400 | 服务器要求会话,但请求没带 Mcp-Session-Id | initialize 响应的头 |
原本正常的调用变成 404 | 会话在服务器侧过期了 | 调用里的 Mcp-Session-Id 头 |
本地桥、fork 客户端,还是改服务器?
一共有四条路。下面按成本从低到高排列,桥故意放在中间:它解决的是两端你都不控制的情况。
| 路径 | 什么时候合适 | 成本 |
|---|---|---|
| 升级客户端 | 你用的版本里已经有新版本支持 | 最低。一次更新加一次重启。 |
| 本地桥 | 服务器要求的版本客户端不支持,而你不想维护 fork | 一个小脚本,不用 fork。 |
| 改服务器 | 服务器归你管,客户端是固定的 | 中等。动的是已经在跑的东西。 |
| fork 客户端 | 几乎永远不需要 | 高。fork 的维护会跟你一辈子。 |
桥是一个本地进程,对客户端说 stdio,对服务器说 HTTP。客户端以为自己连的是一个普通的 MCP 服务器,服务器收到的请求是它要求的版本,两边都不知道中间有人。
四步搭好这座桥
第一步,在项目的 .mcp.json 里把桥声明成一个 stdio 服务器。格式和任何本地服务器一样:command、args、env。
{
"mcpServers": {
"blog": {
"type": "stdio",
"command": "node",
"args": ["/path/to/mcp-bridge.mjs"],
"env": {
"MCP_UPSTREAM": "https://your-server/mcp",
"MCP_UPSTREAM_VERSION": "2025-06-18"
}
}
}
}
第二步,从 stdin 一行一条地读 JSON-RPC。第三步,把每条消息用 POST 连上正确的请求头转给端点。第四步,把响应写回 stdout,并保存 Mcp-Session-Id 供后面的调用使用。
下面的脚本把这四步都做了。它就是整座桥,除了 node 没有别的依赖:
#!/usr/bin/env node
// stdio -> Streamable HTTP 桥
const UPSTREAM = process.env.MCP_UPSTREAM;
const VERSION = process.env.MCP_UPSTREAM_VERSION;
let sessionId = null;
let clientVersion = null;
let buf = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
buf += chunk;
let i;
while ((i = buf.indexOf("\n")) !== -1) {
const line = buf.slice(0, i).trim();
buf = buf.slice(i + 1);
if (line) forward(line);
}
});
async function forward(raw) {
const msg = JSON.parse(raw);
// 记住客户端请求的版本
if (msg.method === "initialize") {
clientVersion = msg.params?.protocolVersion ?? null;
}
const headers = {
"Content-Type": "application/json",
Accept: "application/json, text/event-stream",
"MCP-Protocol-Version": VERSION,
};
if (sessionId) headers["Mcp-Session-Id"] = sessionId;
const res = await fetch(UPSTREAM, { method: "POST", headers, body: raw });
const sid = res.headers.get("mcp-session-id");
if (sid) sessionId = sid;
if (res.status === 202 || res.status === 204) return;
const type = res.headers.get("content-type") || "";
if (type.includes("text/event-stream")) {
const reader = res.body.getReader();
const dec = new TextDecoder();
let rest = "";
for (;;) {
const { value, done } = await reader.read();
if (done) break;
rest += dec.decode(value, { stream: true });
let j;
while ((j = rest.indexOf("\n\n")) !== -1) {
const event = rest.slice(0, j);
rest = rest.slice(j + 2);
for (const l of event.split("\n")) {
if (l.startsWith("data:")) emit(l.slice(5).trim());
}
}
}
return;
}
emit(await res.text());
}
function emit(text) {
if (!text) return;
let out = text.trim();
// 返回的版本不是客户端请求的那个,客户端就会断开
try {
const msg = JSON.parse(out);
if (msg.result && clientVersion && msg.result.protocolVersion) {
msg.result.protocolVersion = clientVersion;
out = JSON.stringify(msg);
}
} catch {}
process.stdout.write(out + "\n");
}
桥跑起来之后,打开 Verboo Code 输入 /mcp。服务器应该显示已连接,并带上工具数量。如果显示已连接但列表为空,问题就不在传输层了,在能力协商。
桥必须保住哪些东西?
周一出问题的地方通常不是 initialize,而是后面的细节。下面几个是我们花时间最多的:
Accept要同时列出两种类型。 客户端和桥都要接受application/json和text/event-stream,因为服务器可以选任意一种来回应。- 会话要带在每次调用上。 服务器在
initialize里返回Mcp-Session-Id之后,后面每个请求都要重复这个头。要求会话的服务器在头缺失时一般会回400。 - 带会话的
404表示会话已经死了。 正确的做法是丢掉这个 id,重新发一个不带会话的initialize,而不是拿旧 id 重试。 - SSE 不能在响应之前关闭。 服务器用流式回应时,每个
data:事件都是一条 JSON-RPC 消息。全部转发,并且在带来该请求响应的事件之前不要结束流。 - 返回的版本必须是客户端请求的那个。 如果桥原样转发服务器的
protocolVersion,客户端会在握手里断开。上面脚本里的emit函数就是在改这个字段。
桥不该做的是翻译语义。如果新版本改了工具结果的格式、资源的错误字段或者授权流程,改写信封只会把问题推到第一次真实调用。桥解决的是信封和请求头的差异,不是契约的差异。
什么时候桥不是答案?
有三种情况,值得在动手写脚本之前先停下来:
- 差异在契约上。 如果
tools/call的结构变了,桥就会变成你永远要维护的兼容层。去升级你能控制的那一端。 - 差异在传输层上。 旧的 SSE 服务器对新的 Streamable HTTP 客户端,靠请求头解决不了。这需要真正的传输适配,用一个已经做好的 SDK 更划算。
- 认证变了。 如果新版本要求客户端没有实现的 OAuth 流程,桥就得替你带着 token。那就不再是桥,而是中间的凭证问题。
我们的情况是三种里最简单的:语义一样,信封和请求头不同。一个下午的工作,零 fork,客户端恢复列出工具,而且完全不知道中间有人。
如果你的 MCP 服务器返回的版本客户端不支持,路径是一样的:在 initialize 里查清两边的版本,写好桥,注册到 .mcp.json,再用 /mcp 确认。Verboo Code 支持在同一个文件里配置 stdio、sse 和 http 服务器,所以桥和任何本地服务器一样接进去就行。跑一次同样的握手,看看两端各说哪个版本。

![[CC] 卡住 15 分钟毫无响应:怎样脱身](/_next/image?url=https%3A%2F%2Fstorage.googleapis.com%2Fverboo-landing-page%2Fblog-uploads%2F1783232445352-verboo-code-cover.png&w=3840&q=75)