Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/stdio-pinned-unsupported-protocol-version.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@modelcontextprotocol/server': patch
---

Reject a request on a `serveStdio` connection pinned to the 2026-07-28 revision when that request's `_meta` envelope names a protocol version the server does not implement. The response is `-32022` with the supported list, and the method does not run. An unknown method is still `-32601`, and a missing or malformed envelope is still `-32602`.
54 changes: 49 additions & 5 deletions packages/server/src/server/serveStdio.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,13 @@
* The entry owns the stdio transport and the era decision for the connection.
* It classifies the connection's opening exchange exactly once (using the
* same body-primary rules as the HTTP entry), constructs ONE server instance
* from the consumer's factory for the era the client opened with, pins that
* instance for the lifetime of the connection, and passes every later message
* straight through to it. No per-message era classification ever runs after
* the connection is pinned — exactly mirroring how `createMcpHandler`
* classifies an HTTP request before any instance exists.
* from the consumer's factory for the era the client opened with, and pins
* that instance for the lifetime of the connection. Later messages pass
* through to that instance. A modern request whose envelope names a revision
* this entry does not serve is answered with `-32022` before the instance
* runs it. No per-message era classification ever runs after the connection
* is pinned — exactly mirroring how `createMcpHandler` classifies an HTTP
* request before any instance exists.
*
* The opening exchange:
*
Expand Down Expand Up @@ -59,13 +61,15 @@ import type {
} from '@modelcontextprotocol/core-internal';
import {
carriesValidModernEnvelopeClaim,
codecForVersion,
envelopeClaimVersion,
extensionsSettled,
hasEnvelopeClaim,
isJSONRPCErrorResponse,
isJSONRPCNotification,
isJSONRPCRequest,
isJSONRPCResultResponse,
MODERN_WIRE_REVISION,
modernOnlyStrictRejection,
ProtocolErrorCode,
requestMetaOf,
Expand Down Expand Up @@ -339,6 +343,32 @@ function classifyOpeningMessage(message: JSONRPCRequest | JSONRPCNotification):
return { kind: 'modern', revision: claimedVersion, classification: { era: 'modern', revision: claimedVersion } };
}

/**
* Revision a modern-pinned request must be rejected for before dispatch.
* `undefined` leaves the answer to the instance: an unknown method is
* `-32601` and a missing or malformed envelope is `-32602`, and both outrank
* an unsupported revision.
*/
function unsupportedPinnedRevision(message: JSONRPCRequest): string | undefined {
// Method existence is the instance's -32601. Only a method the modern
// registry actually serves can reach the revision check.
if (!codecForVersion(MODERN_WIRE_REVISION).hasRequestMethod(message.method)) {
return undefined;
}
if (!hasEnvelopeClaim(message.params)) {
return undefined;
}
const meta = requestMetaOf(message.params);
if (meta === undefined || validateEnvelopeMeta(meta).length > 0) {
return undefined;
}
const claimedVersion = envelopeClaimVersion(message.params);
if (claimedVersion !== undefined && SUPPORTED_MODERN_PROTOCOL_VERSIONS.includes(claimedVersion)) {
return undefined;
}
return claimedVersion ?? 'unknown';
}

/* ------------------------------------------------------------------------ *
* The entry
* ------------------------------------------------------------------------ */
Expand Down Expand Up @@ -606,6 +636,20 @@ export function serveStdio(factory: McpServerFactory, options: ServeStdioOptions
// buffered final message can race stdin EOF): stay closed.
return;
}
if (state.era === 'modern' && isJSONRPCRequest(message)) {
const requested = unsupportedPinnedRevision(message);
if (requested !== undefined) {
// Same -32022 the opening classifier and the HTTP entry
// answer, before the pinned instance can run the method.
const error = new UnsupportedProtocolVersionError({
supported: [...SUPPORTED_MODERN_PROTOCOL_VERSIONS],
requested
});
reportError(error);
await writeErrorResponse(message.id, error.code, error.message, error.data);
return;
}
}
state.instance.channel.deliver(message);
return;
}
Expand Down
96 changes: 95 additions & 1 deletion packages/server/test/server/serveStdio.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,10 @@
* - `legacy: 'reject'` answers legacy openings with the same error and never
* pins a legacy instance;
* - malformed and unsupported envelope claims are answered by the entry,
* consistent with the HTTP entry's treatment, without pinning.
* consistent with the HTTP entry's treatment, without pinning;
* - once the modern era is pinned, a later request naming a revision the
* entry does not serve is answered `-32022` before the method runs.
* An unknown method stays `-32601` and a malformed envelope stays `-32602`.
*/
import { Readable, Writable } from 'node:stream';

Expand Down Expand Up @@ -579,6 +582,97 @@ describe('malformed and unsupported envelope claims (entry-answered, never pinne
});
});

describe('unsupported revision on a modern-pinned connection', () => {
it('answers -32022 and does not run the method when a later request names a revision the entry does not serve', async () => {
let calls = 0;
const eras: Array<'legacy' | 'modern'> = [];
const factory: McpServerFactory = ctx => {
eras.push(ctx.era);
const server = new McpServer({ name: 'serve-stdio-test-server', version: '1.0.0' }, { capabilities: { tools: {} } });
server.registerTool('echo', { inputSchema: z.object({ text: z.string() }) }, ({ text }) => {
calls += 1;
return { content: [{ type: 'text', text }] };
});
return server;
};
const { handle, request } = await startEntryWith(factory);

const pin = await request({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: { _meta: envelope() } });
expect(isJSONRPCResultResponse(pin)).toBe(true);

const expectUnsupported = async (id: number, method: string, protocolVersion: string, params: Record<string, unknown> = {}) => {
const response = await request({
jsonrpc: '2.0',
id,
method,
params: { ...params, _meta: envelope({ [PROTOCOL_VERSION_META_KEY]: protocolVersion }) }
});
expect(isJSONRPCErrorResponse(response)).toBe(true);
if (isJSONRPCErrorResponse(response)) {
expect(response.error.code).toBe(-32_022);
expect(response.error.message).toBe(`Unsupported protocol version: ${protocolVersion}`);
const data = response.error.data as { supported?: string[]; requested?: string };
expect(data.supported).toEqual([MODERN]);
expect(data.requested).toBe(protocolVersion);
}
};

// The same requests the opening window rejects, after the pin.
await expectUnsupported(2, 'server/discover', '2099-01-01');
await expectUnsupported(3, 'tools/list', '2099-01-01');
await expectUnsupported(4, 'tools/call', '2099-01-01', { name: 'echo', arguments: { text: 'should not run' } });
await expectUnsupported(5, 'tools/list', '2025-11-25');
expect(calls).toBe(0);

const again = await request({ jsonrpc: '2.0', id: 6, method: 'tools/list', params: { _meta: envelope() } });
expect(isJSONRPCResultResponse(again)).toBe(true);
const ran = await request({
jsonrpc: '2.0',
id: 7,
method: 'tools/call',
params: { name: 'echo', arguments: { text: 'after' }, _meta: envelope() }
});
expect(isJSONRPCResultResponse(ran)).toBe(true);
expect(calls).toBe(1);
// The rejection did not rebuild the instance or unpin the connection.
expect(eras).toEqual(['modern']);

await handle.close();
});

it('keeps -32601 for an unknown method and -32602 for a malformed envelope ahead of the revision check', async () => {
const { handle, request } = await startEntry();
const pin = await request({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: { _meta: envelope() } });
expect(isJSONRPCResultResponse(pin)).toBe(true);

const unknown = await request({
jsonrpc: '2.0',
id: 2,
method: 'nope',
params: { _meta: envelope({ [PROTOCOL_VERSION_META_KEY]: '2099-01-01' }) }
});
expect(isJSONRPCErrorResponse(unknown)).toBe(true);
if (isJSONRPCErrorResponse(unknown)) {
expect(unknown.error.code).toBe(-32_601);
expect(unknown.error.message).toBe('Method not found');
}

const malformed = await request({
jsonrpc: '2.0',
id: 3,
method: 'tools/list',
params: { _meta: { [PROTOCOL_VERSION_META_KEY]: '2099-01-01' } }
});
expect(isJSONRPCErrorResponse(malformed)).toBe(true);
if (isJSONRPCErrorResponse(malformed)) {
expect(malformed.error.code).toBe(-32_602);
expect(malformed.error.message).toContain('Invalid _meta envelope');
}

await handle.close();
});
});

describe('factory or connect failure during the opening exchange (entry-answered, never pinned)', () => {
it('answers a legacy opening with -32603 when the factory throws, reports the error, and leaves the connection unpinned', async () => {
const { factory: workingFactory, eras } = trackingFactory();
Expand Down
Loading