Skip to content

Commit 75dc7ea

Browse files
fix(server): reject a modern POST without the required MCP-Protocol-Version header (modelcontextprotocol#2590)
Co-authored-by: Konstantin Konstantinov <konstantin@mach5technology.com> Co-authored-by: Konstantin Konstantinov <KKonstantinov@users.noreply.github.com>
1 parent 03842cd commit 75dc7ea

16 files changed

Lines changed: 328 additions & 43 deletions
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
'@modelcontextprotocol/core-internal': patch
3+
'@modelcontextprotocol/server': patch
4+
---
5+
6+
Reject a modern (2026-07-28) POST that omits the required `MCP-Protocol-Version` header.
7+
8+
`createMcpHandler` accepted a request whose body carried a valid per-request `_meta`
9+
envelope but whose `MCP-Protocol-Version` header was absent: the request was classified
10+
modern, dispatched, and answered `200` — tool handlers ran. Only the _mismatch_ case
11+
(header present, disagreeing with the body) was rejected, so of the standard headers
12+
SEP-2243 requires on a modern POST, presence was enforced for `Mcp-Method` (and for
13+
`Mcp-Name` on the methods that mirror `params.name` / `params.uri`) but not for
14+
`MCP-Protocol-Version`.
15+
16+
Such a request is now refused with `400 Bad Request` and JSON-RPC `-32020`
17+
(`HeaderMismatch`), matching the shape the sibling missing-header cells already emit and
18+
echoing the request id — per the Streamable HTTP spec, which requires the header on every
19+
POST and lists a missing required standard header as a `HeaderMismatch` failure. The
20+
spec's allowance to treat a header-less request as `2025-03-26` is available only to a
21+
server that also serves pre-2025-06-18 clients, and permits routing it to _legacy_
22+
handling — never serving it as 2026-07-28; under `legacy: 'reject'` the requirement is
23+
unconditional.
24+
25+
Era classification is deliberately unchanged and stays body-primary: a proxy that strips
26+
the header still must not change the era, so such a request is still _classified_ modern
27+
and is refused one rung later, at `standard-header-validation` — the same rung that
28+
already answers a missing `Mcp-Method`. Legacy-era traffic is untouched, notifications
29+
are unaffected, body-less `GET` / `DELETE` session operations are method-routed before
30+
any header validation, and stdio serving (which has no HTTP headers) is not involved.
31+
32+
Clients built with this SDK always send the header, so no first-party client is affected;
33+
hand-rolled clients that omitted it must add it.

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

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -636,7 +636,19 @@ present body value, malformed, or disagree with the body — `400 Bad Request` w
636636
JSON-RPC `-32020` (`HeaderMismatch`). The Streamable HTTP transport also emits the
637637
`Mcp-Name` standard header on every modern-enveloped request, and `createMcpHandler`
638638
validates the SEP-2243 standard headers (`MCP-Protocol-Version`, `Mcp-Method`,
639-
`Mcp-Name`) against the body on the modern path with the same rejection.
639+
`Mcp-Name`) against the body on the modern path with the same rejection — both their
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.
640652

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

‎packages/core-internal/src/shared/inboundClassification.ts‎

Lines changed: 46 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,15 @@
1717
* named revision belongs to (a malformed envelope behind a present claim is
1818
* a validation error, never a silent fall back to legacy handling).
1919
* - A request without a claim is legacy-era traffic.
20-
* - The `MCP-Protocol-Version` header is a cross-check only: it never
21-
* upgrades or downgrades a body-derived classification, and a disagreement
22-
* between header and body is an explicit ladder outcome.
20+
* - The `MCP-Protocol-Version` header is a cross-check only *for
21+
* classification*: it never upgrades or downgrades a body-derived
22+
* classification, and a disagreement between header and body is an explicit
23+
* ladder outcome. Its absence likewise never changes the era — but the spec
24+
* requires the header on every modern *request* POST, so a
25+
* modern-classified request that omits it is refused one rung later, by
26+
* {@linkcode validateStandardRequestHeaders}, not here. Notification POSTs
27+
* are exempt (see the next bullet), and that rung enforces presence on
28+
* requests only.
2329
* - Notifications carry no envelope claim of their own under the current
2430
* spec, so for notification POSTs without a body claim the modern header is
2531
* determinative; the `Mcp-Method` header is validated against the body when
@@ -320,10 +326,17 @@ export const INBOUND_VALIDATION_LADDER: readonly InboundValidationRungDescriptor
320326
codes: [HEADER_MISMATCH_ERROR_CODE],
321327
conformance: ['http-header-validation'],
322328
rationale:
323-
'SEP-2243 standard `Mcp-Method` / `Mcp-Name` headers — presence, sentinel decoding, and `Mcp-Name` ↔ body cross-check ' +
324-
'— are validated by the HTTP entry on a modern-classified request after the supported-revision gate and before ' +
325-
'dispatch. The classifier’s own header-mismatch cells (protocol-version, `Mcp-Method` mismatch) stay on the edge ' +
326-
'`era-classification` rung; this rung carries the entry-layer presence/`Mcp-Name` half. Evaluated before the ' +
329+
'SEP-2243 standard `MCP-Protocol-Version` / `Mcp-Method` / `Mcp-Name` headers — presence, sentinel decoding, and ' +
330+
'`Mcp-Name` ↔ body cross-check — are validated by the HTTP entry on a modern-classified request after the ' +
331+
'supported-revision gate and before dispatch. The spec requires `MCP-Protocol-Version` and `Mcp-Method` on every ' +
332+
'modern *request* POST (`Mcp-Name` only for the methods that mirror `params.name` / `params.uri`) and names them ' +
333+
'in that order, so a request missing several is answered by the earliest. Notification POSTs are exempt: the ' +
334+
'presence half runs on requests only, so a modern-enveloped notification is dispatched even with no standard ' +
335+
'headers at all. The classifier’s own header-mismatch cells ' +
336+
'(protocol-version, `Mcp-Method` mismatch) stay on the edge ' +
337+
'`era-classification` rung; this rung carries the entry-layer presence/`Mcp-Name` half — including the missing ' +
338+
'`MCP-Protocol-Version` cell, which cannot live on the edge rung without breaking body-primary classification. ' +
339+
'Evaluated before the ' +
327340
'capability gate, the factory call, and the `Mcp-Param-*` rung so a request that fails several rungs is answered by ' +
328341
'the standard-header rung first. The documented order (after method-registry 5 and request-params 6) is NOT the ' +
329342
'observed precedence: serveModern evaluates this rung immediately after the supported-revision gate, so a request ' +
@@ -494,6 +507,10 @@ function stripHttpOws(value: string): string {
494507
* `era-classification` rung for the `MCP-Protocol-Version` and
495508
* `Mcp-Method` *mismatch* cells) when:
496509
*
510+
* - the required `MCP-Protocol-Version` header is absent (SEP-2243 requires it
511+
* on every modern *request* POST, and lists it first among the required
512+
* standard headers — so a request missing it *and* `Mcp-Method` is answered
513+
* by this cell);
497514
* - the required `Mcp-Method` header is absent;
498515
* - the required `Mcp-Name` header is absent on a `tools/call`,
499516
* `prompts/get`, or `resources/read` request whose body carries the
@@ -511,14 +528,35 @@ function stripHttpOws(value: string): string {
511528
* call to the classifier (no headers passed) keeps routing a modern request
512529
* unchanged: the classifier remains a pure body-primary router, and this
513530
* function is the presence/`Mcp-Name` half of the standard-header rung the
514-
* entry layers on top.
531+
* entry layers on top. That separation is what lets the missing
532+
* `MCP-Protocol-Version` cell live here without disturbing the body-primary
533+
* rule — classification still resolves from the body (a proxy stripping the
534+
* header must not change the era), and only this rung refuses to serve it.
515535
*/
516536
export function validateStandardRequestHeaders(request: InboundHttpRequest, route: InboundModernRoute): InboundLadderRejection | undefined {
517537
if (route.messageKind !== 'request') {
518538
return undefined;
519539
}
520540
const method = route.message.method;
521541

542+
// SEP-2243 names `MCP-Protocol-Version` first among the required standard
543+
// headers, so a request missing both it and `Mcp-Method` is answered by
544+
// the header the spec names first. The presence check lives here rather
545+
// than in `classifyInboundRequest` on purpose: classification stays
546+
// body-primary (a proxy stripping the header must not change the era), and
547+
// only this rung refuses to serve the request.
548+
if (request.protocolVersionHeader === undefined) {
549+
const claimed = route.classification.revision;
550+
return crossCheckMismatch(
551+
'version-header-missing',
552+
'(missing)',
553+
claimed === undefined
554+
? 'the body carries a modern per-request envelope but the required MCP-Protocol-Version header is absent'
555+
: `the body envelope names protocol version ${claimed} but the required MCP-Protocol-Version header is absent`,
556+
'standard-header-validation'
557+
);
558+
}
559+
522560
if (request.mcpMethodHeader === undefined) {
523561
return crossCheckMismatch(
524562
'method-header-missing',

‎packages/core-internal/test/shared/inboundLadderCellSheet.test.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,11 @@ const SHEET: readonly SheetRow[] = [
7676
conformance: ['server-stateless'],
7777
input: post(enveloped('tools/call', { name: 'echo', arguments: {} })),
7878
route: 'modern',
79-
rationale: 'Body-primary classification: a proxy stripping the protocol-version header must not change the era.'
79+
rationale:
80+
'Body-primary classification: a proxy stripping the protocol-version header must not change the era. This cell pins ' +
81+
'the CLASSIFICATION only — such a request is still refused before dispatch by the standard-header rung, which requires ' +
82+
'the header the spec mandates on every modern *request* POST (see validateStandardRequestHeaders / ' +
83+
'version-header-missing). A notification POST is exempt from that rung and stays served.'
8084
},
8185
{
8286
cell: 'legacy-claimless-request',

‎packages/core-internal/test/shared/standardHeaderValidation.test.ts‎

Lines changed: 59 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@
44
*
55
* Evaluated by the HTTP entry on a modern-classified request immediately
66
* after `classifyInboundRequest` returns a modern route: rejects `400` /
7-
* `-32020` (`HeaderMismatch`) when the required `Mcp-Method` header is
7+
* `-32020` (`HeaderMismatch`) when the required `MCP-Protocol-Version` header
8+
* is absent, when the required `Mcp-Method` header is
89
* absent, when the required `Mcp-Name` header is absent on a `tools/call` /
910
* `prompts/get` / `resources/read` request, when the `Mcp-Name` header
1011
* carries an invalid Base64 sentinel, and when its (decoded) value disagrees
@@ -60,6 +61,55 @@ function expectRejection(result: InboundLadderRejection | undefined, cell: strin
6061
expect(result?.settled).toBe(true);
6162
}
6263

64+
describe('SEP-2243 standard-header validation (MCP-Protocol-Version presence)', () => {
65+
test('a modern request without an MCP-Protocol-Version header is rejected (version-header-missing)', () => {
66+
const request: InboundHttpRequest = {
67+
httpMethod: 'POST',
68+
mcpMethodHeader: 'tools/list',
69+
body: { jsonrpc: '2.0', id: 1, method: 'tools/list', params: { _meta: ENVELOPE } }
70+
};
71+
const outcome = classifyInboundRequest(request);
72+
// Body-primary classification is deliberately untouched: a proxy that
73+
// strips the header must not change the era, so the request still
74+
// routes modern and the rejection belongs to this rung — not to the
75+
// classifier.
76+
expect(outcome.kind).toBe('modern');
77+
expectRejection(validateStandardRequestHeaders(request, outcome as InboundModernRoute), 'version-header-missing');
78+
});
79+
80+
test('the missing-version cell outranks the missing-method cell (spec header order)', () => {
81+
const request: InboundHttpRequest = {
82+
httpMethod: 'POST',
83+
body: { jsonrpc: '2.0', id: 1, method: 'tools/list', params: { _meta: ENVELOPE } }
84+
};
85+
const outcome = classifyInboundRequest(request);
86+
expect(outcome.kind).toBe('modern');
87+
expectRejection(validateStandardRequestHeaders(request, outcome as InboundModernRoute), 'version-header-missing');
88+
});
89+
90+
test('a present and matching MCP-Protocol-Version header passes', () => {
91+
const { request, route } = modernPost('tools/list', {}, { mcpMethod: 'tools/list' });
92+
expect(validateStandardRequestHeaders(request, route)).toBeUndefined();
93+
});
94+
95+
test('the header/body version mismatch cell stays inside classifyInboundRequest (this rung never sees it)', () => {
96+
// The protocol-version check is split across two rungs: *absence* is
97+
// this rung's cell, *disagreement* stays on the classifier's edge
98+
// `era-classification` rung. Pinned so the split stays observable —
99+
// the same guard the Mcp-Method pair carries below.
100+
const outcome = classifyInboundRequest({
101+
httpMethod: 'POST',
102+
protocolVersionHeader: '2025-11-25',
103+
mcpMethodHeader: 'tools/list',
104+
body: { jsonrpc: '2.0', id: 1, method: 'tools/list', params: { _meta: ENVELOPE } }
105+
});
106+
expect(outcome.kind).toBe('reject');
107+
expect((outcome as InboundLadderRejection).cell).toBe('header-body-version-mismatch');
108+
expect((outcome as InboundLadderRejection).rung).toBe('era-classification');
109+
expect((outcome as InboundLadderRejection).code).toBe(-32_020);
110+
});
111+
});
112+
63113
describe('SEP-2243 standard-header validation (Mcp-Method presence)', () => {
64114
test('a modern request without an Mcp-Method header is rejected (method-header-missing)', () => {
65115
const { request, route } = modernPost('tools/list', {});
@@ -86,7 +136,14 @@ describe('SEP-2243 standard-header validation (Mcp-Method presence)', () => {
86136
expect((outcome as InboundLadderRejection).cell).toBe('method-header-mismatch');
87137
});
88138

89-
test('notifications are never enforced', () => {
139+
test('notifications are never enforced — including the MCP-Protocol-Version presence cell', () => {
140+
// Deliberate, not an oversight. The Streamable HTTP "Sending Messages"
141+
// note states that "header requirements for notification POSTs are not
142+
// defined by this revision" (the revision defines no client-to-server
143+
// notifications over Streamable HTTP at all), so the "Every POST
144+
// request MUST include an MCP-Protocol-Version header" rule does not
145+
// reach a posted notification and this rung stays request-only.
146+
// The request below carries NO standard headers whatsoever.
90147
const route: InboundModernRoute = {
91148
kind: 'modern',
92149
messageKind: 'notification',

‎packages/middleware/node/test/toNodeHandler.test.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,9 @@ function modernToolsCall(name: string, args: Record<string, unknown>): unknown {
4040
function bodyDerivedStandardHeaders(body: unknown): Record<string, string> {
4141
if (body === null || typeof body !== 'object' || Array.isArray(body)) return {};
4242
const b = body as { method?: unknown; params?: { name?: unknown; uri?: unknown; _meta?: Record<string, unknown> } };
43-
if (typeof b.params?._meta?.[PROTOCOL_VERSION_META_KEY] !== 'string') return {};
44-
const out: Record<string, string> = {};
43+
const claimedVersion = b.params?._meta?.[PROTOCOL_VERSION_META_KEY];
44+
if (b.params === undefined || typeof claimedVersion !== 'string') return {};
45+
const out: Record<string, string> = { 'mcp-protocol-version': claimedVersion };
4546
if (typeof b.method === 'string') out['mcp-method'] = b.method;
4647
const name = b.method === 'resources/read' ? b.params.uri : b.params.name;
4748
if (typeof name === 'string') out['mcp-name'] = name;

0 commit comments

Comments
 (0)