Skip to content

[v2] serveStdio stops checking the protocol version once a connection is pinned to 2026-07-28 #3179

Open

Description

@chenxin-yan

What happened?

A stdio server started with serveStdio(factory) checks a request's protocol version only until the connection is pinned. Once an enveloped request has pinned the connection to 2026-07-28, a later request whose _meta envelope names a version the server does not implement is served normally. (A server/discover probe alone does not pin, so requests in the probe window are still checked.)

Output of the script below on 2.4.0 (Node 26.13.0; Bun 1.4.4 gives the same four outcomes). Requests 1 and 3 are identical; only the pin in between differs:

1 server/discover @ 2099-01-01 -> {"jsonrpc":"2.0","id":1,"error":{"code":-32022,"message":"Unsupported protocol version: 2099-01-01","data":{"supported":["2026-07-28"],"requested":"2099-01-01"}}}
2 tools/list @ 2026-07-28 -> {"result":{"tools":[],"resultType":"complete","ttlMs":0,"cacheScope":"private","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"repro","version":"1.0.0"}}},"jsonrpc":"2.0","id":2}
3 server/discover @ 2099-01-01 -> {"result":{"supportedVersions":["2026-07-28"],"capabilities":{"tools":{}},"resultType":"complete","ttlMs":0,"cacheScope":"private","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"repro","version":"1.0.0"}}},"jsonrpc":"2.0","id":3}
4 tools/list @ 2099-01-01 -> {"result":{"tools":[],"resultType":"complete","ttlMs":0,"cacheScope":"private","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"repro","version":"1.0.0"}}},"jsonrpc":"2.0","id":4}

The same happens for tools/call (the tool runs), and an envelope naming 2025-11-25 on a modern-pinned connection is served too.

It does not depend on how the server is built. Server and McpServer, with supportedProtocolVersions listed, with enforceStrictCapabilities, and with legacy: 'reject' all behave this way.

The HTTP entry answers the same pair of requests correctly. Through createMcpHandler(factory).fetch(...):

2026-07-28 -> HTTP 200 {"result":{"tools":[],"resultType":"complete","ttlMs":0,"cacheScope":"private","_meta":{…}},"jsonrpc":"2.0","id":1}
2099-01-01 -> HTTP 400 {"jsonrpc":"2.0","error":{"code":-32022,"message":"Unsupported protocol version: 2099-01-01","data":{"supported":["2026-07-28"],"requested":"2099-01-01"}},"id":2}

Where it comes from, at the @modelcontextprotocol/server@2.4.0 tag (main is the same in these places as of 919bb8e):

  • packages/server/src/server/serveStdio.ts:577-606: in the pinned phase, an ordinary request goes straight to state.instance.channel.deliver(message). Only messages in the negotiation window (opening and probe) are classified, which is where unsupported-revision produces -32022 (:629-636).
  • packages/core-internal/src/shared/protocol.ts:1038: the instance calls codec.checkInboundEnvelope(lifted).
  • packages/core-internal/src/wire/rev2026-07-28/codec.ts:277-289: checkInboundEnvelope checks that the envelope is present and well-formed. It accepts any string as protocolVersion.
  • The era check that does answer -32022 (protocol.ts:973-1002) runs only when the entry passes extra.classification, which the pinned stdio path does not.

The existing suite covers the two neighbouring cases but not this one: serveStdio.test.ts:240 (a late claim-less initialize after the modern pin answers -32022) and :560 (an unsupported revision on the opening message answers -32022).

What did you expect?

-32022 with data.supported and data.requested for requests 3 and 4, as for request 1.

Pinning the era per connection is fine. This is about the version each modern request declares, which the 2026-07-28 specification makes a per-request property:

  • Protocol Version Negotiation: "Every request declares the protocol version it is using in its _meta field. […] If the server does not implement the requested version (whether the version is unknown to the server, or is a known version the server has chosen not to support), it MUST respond with an UnsupportedProtocolVersionError listing the versions it does support".
  • Statelessness: "Servers MUST NOT rely on prior requests over the same connection to establish context (e.g., capabilities, protocol version, client identity). Every request supplies this metadata in its _meta field."

The conformance suite has this requirement as sep-2575-server-unsupported-version-error (src/scenarios/server/stateless.ts): it sends valid requests and then one naming an unsupported version, and expects -32022. It drives servers over HTTP only, so the stdio path is not exercised.

A client that sends the same supported version on every request is unaffected. A client that changes the version on an open pipe gets its request executed under 2026-07-28 semantics instead of the error.

One possible fix: on a modern-pinned connection, compare the envelope's protocolVersion with the supported modern revisions before dispatch (in the pinned branch of serveStdio, or in checkInboundEnvelope), keeping the current precedence of -32601 for unknown methods and -32602 for a missing or malformed envelope.

Code to reproduce

// repro.mjs — run with: node repro.mjs
import { spawn } from "node:child_process";
import { once } from "node:events";
import { createInterface } from "node:readline";

import { Server } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";

if (process.argv[2] === "server") {
	serveStdio(() => {
		const server = new Server({ name: "repro", version: "1.0.0" }, { capabilities: { tools: {} } });
		server.setRequestHandler("tools/list", () => ({ tools: [] }));
		return server;
	});
} else {
	const child = spawn(process.execPath, [import.meta.filename, "server"], {
		stdio: ["pipe", "pipe", "inherit"],
	});
	const replies = createInterface({ input: child.stdout });
	const send = async (id, method, protocolVersion) => {
		const _meta = {
			"io.modelcontextprotocol/protocolVersion": protocolVersion,
			"io.modelcontextprotocol/clientCapabilities": {},
		};
		child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params: { _meta } })}\n`);
		const [reply] = await once(replies, "line");
		console.log(`${id} ${method} @ ${protocolVersion} -> ${reply}`);
	};
	await send(1, "server/discover", "2099-01-01"); // probe: the connection is not pinned yet
	await send(2, "tools/list", "2026-07-28"); // pins the connection to 2026-07-28
	await send(3, "server/discover", "2099-01-01"); // the same request as 1
	await send(4, "tools/list", "2099-01-01");
	child.stdin.end();
}

SDK version

@modelcontextprotocol/server 2.4.0

Area

Server

Activity

  1. changed the title [-][v2] serveStdio serves a request naming an unsupported protocol version once the connection is pinned to 2026-07-28[/-] [+][v2] serveStdio stops checking the protocol version once a connection is pinned to 2026-07-28[/+] on Nov 12, 2026
  2. gentil93 commented on Nov 12, 2026

    @gentil93

    I'd like to take this.

    Plan:

    1. Add a serveStdio regression for the sequence in the issue: an unsupported server/discover before the pin still returns -32022; after a 2026-07-28 pin, the same unsupported server/discover and a tools/list with an unsupported protocolVersion also return -32022 (data.supported / data.requested). Keep the existing precedence of -32601 for unknown methods and -32602 for a missing or malformed envelope.

    2. On a modern-pinned connection, check the request envelope's protocolVersion against the supported modern revisions before dispatch, so a pinned request is rejected the same way as one in the opening/probe window.

    I'll open a PR with tests once this is in place.

  3. added
    v2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes
    on Nov 13, 2026
  4. media-ctrl commented on Nov 14, 2026

    @media-ctrl
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    v2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions