Skip to content

Commit c02cb2d

Browse files
committed
refactor(server): read the SEP-2243 standard headers once; qualify the notification exemption
Addresses the three review nits on modelcontextprotocol#2590. The entry built two InboundHttpRequest header objects from the same request — one for classifyInboundRequest, one for the standard-header rung — and the divergence between them is what let a modern POST omitting MCP-Protocol-Version be served: the header was read at the classifier site and not at the validation site. Both now spread a single standardHeadersOf(request), so a header added to InboundHttpRequest reaches both sites together. The migration guide claimed the presence half applies to every modern POST. Notification POSTs are exempt — validateStandardRequestHeaders returns early for messageKind !== 'request', which the changeset already said but the guide did not. Qualified, with the reason. Converts the two remaining hand-built modern header sets in protocol.test.ts to modernStandardHeaders(). The deliberate omission in sep2243.test.ts stays: it asserts /Mcp-Method/ in the message and so pins that the classifier's edge rung answers a mismatch before the presence rung runs.
1 parent 9543943 commit c02cb2d

3 files changed

Lines changed: 37 additions & 23 deletions

File tree

‎docs/migration/support-2026-07-28.md‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -637,12 +637,18 @@ JSON-RPC `-32020` (`HeaderMismatch`). The Streamable HTTP transport also emits t
637637
`Mcp-Name` standard header on every modern-enveloped request, and `createMcpHandler`
638638
validates the SEP-2243 standard headers (`MCP-Protocol-Version`, `Mcp-Method`,
639639
`Mcp-Name`) against the body on the modern path with the same rejection — both their
640-
**presence** (all three are required on every modern POST; `Mcp-Name` only for the
641-
methods that mirror `params.name` / `params.uri`) and their agreement with the body. A
642-
modern-enveloped POST that omits `MCP-Protocol-Version` is refused rather than served,
643-
even though the body claim alone still determines the era — so a hand-rolled client that
644-
relied on the body envelope without sending the header must add it. Clients built with
645-
this SDK send all three already.
640+
**presence** (all three are required on every modern **request** POST; `Mcp-Name` only
641+
for the methods that mirror `params.name` / `params.uri`) and their agreement with the
642+
body. A modern-enveloped request POST that omits `MCP-Protocol-Version` is refused rather
643+
than served, even though the body claim alone still determines the era — so a hand-rolled
644+
client that relied on the body envelope without sending the header must add it. Clients
645+
built with this SDK send all three already.
646+
647+
Notification POSTs are exempt from the presence half: this revision defines no
648+
client-to-server notifications over Streamable HTTP, and states that header requirements
649+
for notification POSTs are not defined by it — so a modern-enveloped notification is
650+
dispatched and answered `202` even with no standard headers at all. Do not rely on the
651+
entry to reject one.
646652

647653
**Modern-era exception** to the `SdkHttpError` mapping: on a modern-enveloped request,
648654
an HTTP `400` whose body is a well-formed JSON-RPC error response addressed to the

‎packages/server/src/server/createMcpHandler.ts‎

Lines changed: 22 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ import type {
3131
ClientCapabilities,
3232
Implementation,
3333
InboundClassificationOutcome,
34+
InboundHttpRequest,
3435
InboundLadderRejection,
3536
InboundLegacyRoute,
3637
InboundModernRoute,
@@ -406,6 +407,25 @@ export function legacyStatelessFallback(factory: McpServerFactory, onerror?: (er
406407
* The entry's classification step (shared with isLegacyRequest)
407408
* ------------------------------------------------------------------------ */
408409

410+
/**
411+
* Read the SEP-2243 standard request headers off the inbound request.
412+
*
413+
* Both halves of the standard-header story need them — the body-primary
414+
* classifier for its cross-check cells, and
415+
* {@linkcode validateStandardRequestHeaders} for the presence half — and a
416+
* header read at one site but not the other is precisely how a required header
417+
* goes unenforced: that divergence is what let a modern POST omitting
418+
* `MCP-Protocol-Version` be served. Read them here once so a header added to
419+
* {@linkcode InboundHttpRequest} reaches both sites together.
420+
*/
421+
function standardHeadersOf(request: Request): Omit<InboundHttpRequest, 'httpMethod' | 'body'> {
422+
return {
423+
protocolVersionHeader: request.headers.get('mcp-protocol-version') ?? undefined,
424+
mcpMethodHeader: request.headers.get('mcp-method') ?? undefined,
425+
mcpNameHeader: request.headers.get('mcp-name') ?? undefined
426+
};
427+
}
428+
409429
/** The outcome of the entry's classification step for one inbound HTTP request. */
410430
type EntryClassification =
411431
/** The body bytes could not be read at all (a failing stream, not malformed JSON). */
@@ -467,9 +487,7 @@ async function classifyEntryRequest(request: Request, providedParsedBody?: unkno
467487

468488
const outcome = classifyInboundRequest({
469489
httpMethod,
470-
protocolVersionHeader: request.headers.get('mcp-protocol-version') ?? undefined,
471-
mcpMethodHeader: request.headers.get('mcp-method') ?? undefined,
472-
mcpNameHeader: request.headers.get('mcp-name') ?? undefined,
490+
...standardHeadersOf(request),
473491
...(body !== undefined && { body })
474492
});
475493
return { step: 'classified', outcome, body, parsedBody, forwardRequest };
@@ -674,15 +692,7 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
674692
// before the capability gate, the factory call, and the
675693
// `Mcp-Param-*` rung so a request that fails several rungs is
676694
// answered by the standard-header rung first.
677-
const stdHeaderRejection = validateStandardRequestHeaders(
678-
{
679-
httpMethod: request.method,
680-
protocolVersionHeader: request.headers.get('mcp-protocol-version') ?? undefined,
681-
mcpMethodHeader: request.headers.get('mcp-method') ?? undefined,
682-
mcpNameHeader: request.headers.get('mcp-name') ?? undefined
683-
},
684-
route
685-
);
695+
const stdHeaderRejection = validateStandardRequestHeaders({ httpMethod: request.method, ...standardHeadersOf(request) }, route);
686696
if (stdHeaderRejection !== undefined) {
687697
reportError(new Error(`Rejected inbound request (${stdHeaderRejection.cell}): ${stdHeaderRejection.message}`));
688698
return rejectionResponse(stdHeaderRejection, echoableRequestId(route.message));

‎test/e2e/scenarios/protocol.test.ts‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ import {
3535
import { expect, vi } from 'vitest';
3636
import { z } from 'zod/v4';
3737

38-
import { modernEnvelopeMeta, tapWire, wire } from '../helpers/index';
38+
import { modernEnvelopeMeta, modernStandardHeaders, tapWire, wire } from '../helpers/index';
3939
import { verifies } from '../helpers/verifies';
4040
import type { TestArgs } from '../types';
4141

@@ -1158,8 +1158,7 @@ verifies('protocol:meta:server-identity', async ({ transport }: TestArgs) => {
11581158
headers: {
11591159
'content-type': 'application/json',
11601160
accept: 'application/json, text/event-stream',
1161-
'mcp-protocol-version': '2026-07-28',
1162-
'mcp-method': 'server/discover'
1161+
...modernStandardHeaders('server/discover')
11631162
},
11641163
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'server/discover', params: { _meta: modernEnvelopeMeta() } })
11651164
});
@@ -1184,8 +1183,7 @@ verifies('protocol:envelope:client-info-optional', async ({ transport }: TestArg
11841183
headers: {
11851184
'content-type': 'application/json',
11861185
accept: 'application/json, text/event-stream',
1187-
'mcp-protocol-version': '2026-07-28',
1188-
'mcp-method': 'tools/list'
1186+
...modernStandardHeaders('tools/list')
11891187
},
11901188
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: { _meta: meta } })
11911189
});

0 commit comments

Comments
 (0)