MCP: "Unsupported protocol version" on connect, fixed with a local bridge
Back to the blog
Articleverboo codemcptutorialdev tools

MCP: "Unsupported protocol version" on connect, fixed with a local bridge

MafraNovember 19, 20268 min read

The symptom is quiet on one side and loud on the other. The MCP client connects, the panel shows the server as active, and the tool list comes back empty. In the server log, a bare 400 with no stack trace.

That is what happened when we wired our blog MCP into Verboo Code. The client spoke one revision of the MCP protocol, the server required another. It was not a bug on either side: the protocol expects version negotiation to fail sometimes, and it spells out exactly what each side must do when it does.

The way out we chose was neither forking the client nor rewriting the server. It was a small local bridge in the middle. This article shows why it works and how to build yours.

Why does the MCP protocol revision break the connection?

Because version negotiation happens on the first message and it is not advisory. The client sends initialize with the version it supports, the server answers with its own, and if the client does not support that answer, the correct behavior is to disconnect.

The specification is direct on these points:

  • If the server supports the requested version, it must reply with the same version. Otherwise it must reply with another version it supports, preferably its latest.
  • If the client does not support the version returned by the server, it should disconnect.
  • Over HTTP, the client must send the MCP-Protocol-Version header on every request after initialize, and the server must answer 400 when the version is invalid or unsupported.

The error that shows up in this case is usually this one, with the list of versions the server accepts:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Unsupported protocol version",
    "data": {
      "supported": ["2025-06-18"],
      "requested": "2025-03-26"
    }
  }
}

Keep that data.supported. It is the revision the bridge will need to use upstream.

How do you find which revision each side is on?

From the handshake, without guessing. The first message in any MCP session is initialize, and both versions show up there. You can see it with a curl, before blaming the client:

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" }
    }
  }'

If the response comes back with a protocolVersion different from the one you sent, the server is returning the revision it speaks. If the response carries an Mcp-Session-Id header, write it down: it will be required on every following call.

SymptomLikely causeWhere to look
Server shows as connected, empty tool listClient does not support the revision returned in the handshakeThe initialize response and the -32602 error
400 on every call after the handshakeMCP-Protocol-Version header missing or wrongThe HTTP request the client builds
400 on the very first POSTServer requires a session and the call arrived without Mcp-Session-IdHeaders of the initialize response
404 on calls that used to workSession expired on the server sideThe Mcp-Session-Id header of the call

Local bridge, client fork, or server change?

There are four paths. The order below goes from lowest to highest cost, and the bridge sits in the middle on purpose: it handles the case where you control neither end.

PathWhen it makes senseCost
Update the clientThe new revision is already available in the version you runLowest. One update and a restart.
Local bridgeThe server requires a revision the client does not speak and you do not want to maintain a forkOne small script, no fork.
Update the serverYou control the server and the client is fixedMedium. Touches something already in production.
Fork the clientAlmost neverHigh. You inherit fork maintenance forever.

The bridge is a local process that speaks stdio to the client and HTTP to the server. The client believes it is talking to an ordinary MCP server. The server receives requests in the revision it requires. Neither side knows there is a middleman.

How to build the bridge in four steps

First, declare the bridge as a stdio server in the project's .mcp.json. The format is the same as any local server: command, args, and 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"
      }
    }
  }
}

Second, read the JSON-RPC arriving on stdin, one message per line. Third, forward each message with a POST to the endpoint using the right headers. Fourth, write the response to stdout and keep the Mcp-Session-Id for the following calls.

The script below does all four. It is the whole bridge, with no dependency beyond node:

#!/usr/bin/env node
// stdio -> Streamable HTTP bridge
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);

  // remember the revision the client asked for
  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();

  // the client disconnects if the returned revision is not the one it asked for
  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");
}

With the bridge running, open Verboo Code and type /mcp. The server should show as connected, with a tool count. If it shows connected and empty, the problem is no longer transport: it is capabilities.

What must the bridge preserve?

The part that breaks on Monday is not initialize, it is the details that come after. These are the ones that cost us the most time:

  • Accept must list both types. The client and the bridge should accept application/json and text/event-stream, because the server may choose to answer with either one.
  • The session goes on every call. Once the server returns Mcp-Session-Id in initialize, every following request must repeat the header. A server that requires a session usually answers 400 when it is missing.
  • 404 with a session means a dead session. The right move is to drop the id and send a new initialize without a session, not to retry the call with the old id.
  • SSE does not close before the response. When the server answers as a stream, each data: event is one JSON-RPC message. Forward all of them and do not end the stream before the event that carries the response to the request.
  • The returned revision must be the one the client asked for. If the bridge forwards the server's protocolVersion without rewriting it, the client disconnects during the handshake. That is why the emit function above rewrites that field.

What the bridge must not do is translate semantics. If the new revision changed the result shape of a tool, the error field of a resource, or the authorization flow, rewriting the envelope only pushes the problem to the first real call. A bridge is for envelope and header differences, not for contract differences.

When is the bridge not the answer?

Three cases where it is worth stopping before writing the script:

  • The difference is in the contract. If the shape of tools/call changed, the bridge becomes a compatibility layer you maintain forever. Update the end you control.
  • The difference is in the transport. An old SSE server against a new Streamable HTTP client is not solved with a header. It needs a real transport adaptation, and an SDK that already does it is a better bet.
  • Authentication changed. If the new revision requires an OAuth flow the client does not implement, the bridge would have to carry the token for you. That stops being a bridge and becomes a credential problem in the middle.

Our case was the simplest of the three: same semantics, different envelope and headers. One afternoon of work, zero forks, and the client went back to listing tools without knowing anyone was in the middle.

If your MCP server answers in a revision your client does not speak, the path is the same: find both versions in initialize, write the bridge, register it in .mcp.json, and check it with /mcp. Verboo Code accepts stdio, sse, and http servers in the same file, so the bridge plugs in like any other local server. Run the same handshake and see which revision each side speaks.

Enjoyed this article?
Share knowledge with your network.
// Read also

Related articles