MCP 报 "Unsupported protocol version":用本地桥接修复
返回博客
文章verboo codemcptutorialdev tools

MCP 报 "Unsupported protocol version":用本地桥接修复

Mafra2026年11月19日阅读约 7 分钟

这个故障在一端很安静,在另一端很吵。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 错误
握手之后每个调用都 400MCP-Protocol-Version 头缺失或写错客户端构造的 HTTP 请求
第一个 POST 就 400服务器要求会话,但请求没带 Mcp-Session-Idinitialize 响应的头
原本正常的调用变成 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 服务器,所以桥和任何本地服务器一样接进去就行。跑一次同样的握手,看看两端各说哪个版本。

喜欢这篇文章吗?
把知识分享给你的朋友。
// 继续阅读

相关文章