From 33479283ba47b2f906dc695b8f85281009778463 Mon Sep 17 00:00:00 2001 From: Matt Carey Date: Mon, 9 Nov 2026 17:32:27 +0000 Subject: [PATCH 1/2] fix(server): reject an Mcp-Param header whose body value is an object or array --- .../mcp-param-header-non-primitive-body.md | 6 ++++++ .../src/shared/mcpParamHeaders.ts | 13 ++++++++++++- .../test/shared/mcpParamHeaders.test.ts | 18 ++++++++++++++++++ .../test/server/mcpParamValidation.test.ts | 7 +++++++ 4 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 .changeset/mcp-param-header-non-primitive-body.md diff --git a/.changeset/mcp-param-header-non-primitive-body.md b/.changeset/mcp-param-header-non-primitive-body.md new file mode 100644 index 0000000000..84f4da8d7d --- /dev/null +++ b/.changeset/mcp-param-header-non-primitive-body.md @@ -0,0 +1,6 @@ +--- +'@modelcontextprotocol/core-internal': patch +'@modelcontextprotocol/server': patch +--- + +Reject a `tools/call` with `400` / `-32020` (`HeaderMismatch`) when an `Mcp-Param-*` header is present but the matching body argument is an object or array. Previously the header check was skipped and the call was answered `200` with a tool input-validation error. diff --git a/packages/core-internal/src/shared/mcpParamHeaders.ts b/packages/core-internal/src/shared/mcpParamHeaders.ts index 26631c76f7..4bce1715ac 100644 --- a/packages/core-internal/src/shared/mcpParamHeaders.ts +++ b/packages/core-internal/src/shared/mcpParamHeaders.ts @@ -356,9 +356,20 @@ export function validateMcpParamHeaders( // Server MUST NOT expect the header for a null/absent value. continue; } + if (typeof bodyRaw === 'object') { + // An object or array can never be mirrored into a header, so a + // present header cannot match it. With no header, params + // validation owns the body-vs-schema fault. + if (headerValue === null) continue; + return paramHeaderMismatchRejection( + 'param-header-mismatch', + headerKey, + `the ${headerKey} header is present but the body carries a non-primitive ${pathName(decl.path)}` + ); + } const bodyString = mcpParamPrimitiveToString(bodyRaw); if (bodyString === undefined) { - // Body carries a non-primitive where the schema declares one; + // A non-finite number or an unsafe integer has no header form; // params validation owns that fault. Skip the header check. continue; } diff --git a/packages/core-internal/test/shared/mcpParamHeaders.test.ts b/packages/core-internal/test/shared/mcpParamHeaders.test.ts index fedad8d36f..88026ca355 100644 --- a/packages/core-internal/test/shared/mcpParamHeaders.test.ts +++ b/packages/core-internal/test/shared/mcpParamHeaders.test.ts @@ -287,6 +287,24 @@ describe('validateMcpParamHeaders — server-behavior table', () => { }); }); + test('header present but the body value is an object or array → reject 400/-32020', () => { + const intDecl = [{ path: ['n'], headerName: 'N', type: 'integer' }] as const; + const headers = new Headers({ [`${MCP_PARAM_HEADER_PREFIX}N`]: '5' }); + for (const n of [{ a: 1 }, [5]]) { + expect(validateMcpParamHeaders(intDecl, { n }, headers)).toMatchObject({ + kind: 'reject', + httpStatus: 400, + code: HEADER_MISMATCH_ERROR_CODE, + cell: 'param-header-mismatch' + }); + } + }); + + test('header absent and the body value is an object → ok (params validation owns it)', () => { + const intDecl = [{ path: ['n'], headerName: 'N', type: 'integer' }] as const; + expect(validateMcpParamHeaders(intDecl, { n: { a: 1 } }, new Headers())).toBeUndefined(); + }); + test('invalid Base64 sentinel → reject 400/-32020', () => { const r = validateMcpParamHeaders( DECLS, diff --git a/packages/server/test/server/mcpParamValidation.test.ts b/packages/server/test/server/mcpParamValidation.test.ts index 15f78c32eb..c8ebb8bfc3 100644 --- a/packages/server/test/server/mcpParamValidation.test.ts +++ b/packages/server/test/server/mcpParamValidation.test.ts @@ -115,6 +115,13 @@ describe('SEP-2243 Mcp-Param-* server validation (createMcpHandler, modern era)' expect(r2.status).toBe(200); }); + it('a present header with an object body value is rejected 400/-32020 before argument validation', async () => { + const handler = createMcpHandler(makeFactory()); + const response = await handler.fetch(call({ region: { nested: 'us-west1' } }, { 'Mcp-Param-Region': 'us-west1' })); + expect(response.status).toBe(400); + expect(((await response.json()) as { error: { code: number } }).error.code).toBe(-32_020); + }); + it('an invalid Base64 sentinel is rejected 400/-32020', async () => { const handler = createMcpHandler(makeFactory()); const response = await handler.fetch(call({ region: 'Hello' }, { 'Mcp-Param-Region': '=?base64?SGVsbG8?=' })); From 45c03c9bd9df76b17e6b7cd97cfb7b9dceee016e Mon Sep 17 00:00:00 2001 From: Matt Carey Date: Mon, 9 Nov 2026 18:53:43 +0000 Subject: [PATCH 2/2] fix(server): reject Mcp-Param values the header check cannot verify An object or array body value for an x-mcp-header argument is now rejected whether or not its header is present. Leaving the no-header case to params validation was not safe: a coercing schema such as z.coerce.string() turns ["eu"] into "eu", so the tool ran with a value no header carried. An integer outside the safe range has no header form. A present header cannot be compared with it, so it is rejected; an absent header is still accepted, because the SDK's own client omits the header for such values. --- .../mcp-param-header-non-primitive-body.md | 2 +- .../src/shared/mcpParamHeaders.ts | 27 ++++++++++++------- .../test/shared/mcpParamHeaders.test.ts | 21 +++++++++++++-- 3 files changed, 37 insertions(+), 13 deletions(-) diff --git a/.changeset/mcp-param-header-non-primitive-body.md b/.changeset/mcp-param-header-non-primitive-body.md index 84f4da8d7d..bccc0bcdb0 100644 --- a/.changeset/mcp-param-header-non-primitive-body.md +++ b/.changeset/mcp-param-header-non-primitive-body.md @@ -3,4 +3,4 @@ '@modelcontextprotocol/server': patch --- -Reject a `tools/call` with `400` / `-32020` (`HeaderMismatch`) when an `Mcp-Param-*` header is present but the matching body argument is an object or array. Previously the header check was skipped and the call was answered `200` with a tool input-validation error. +Reject a `tools/call` with `400` / `-32020` (`HeaderMismatch`) when a body argument declared with `x-mcp-header` is an object or array, with or without its `Mcp-Param-*` header, and when the argument is an integer outside the safe range but the header is present. Previously the header check was skipped for these values, so the call reached the tool. diff --git a/packages/core-internal/src/shared/mcpParamHeaders.ts b/packages/core-internal/src/shared/mcpParamHeaders.ts index 4bce1715ac..3b1861df36 100644 --- a/packages/core-internal/src/shared/mcpParamHeaders.ts +++ b/packages/core-internal/src/shared/mcpParamHeaders.ts @@ -356,23 +356,30 @@ export function validateMcpParamHeaders( // Server MUST NOT expect the header for a null/absent value. continue; } + // An object or array has no header form: reject it with or without a header. if (typeof bodyRaw === 'object') { - // An object or array can never be mirrored into a header, so a - // present header cannot match it. With no header, params - // validation owns the body-vs-schema fault. + return headerValue === null + ? paramHeaderMismatchRejection( + 'param-header-missing', + headerKey, + `the body carries a non-primitive ${pathName(decl.path)} but the ${headerKey} header is absent` + ) + : paramHeaderMismatchRejection( + 'param-header-mismatch', + headerKey, + `the ${headerKey} header is present but the body carries a non-primitive ${pathName(decl.path)}` + ); + } + const bodyString = mcpParamPrimitiveToString(bodyRaw); + if (bodyString === undefined) { + // No header form (unsafe integer): an absent header is expected, a present one cannot be verified. if (headerValue === null) continue; return paramHeaderMismatchRejection( 'param-header-mismatch', headerKey, - `the ${headerKey} header is present but the body carries a non-primitive ${pathName(decl.path)}` + `the ${headerKey} header cannot be compared with ${pathName(decl.path)}=${JSON.stringify(bodyRaw)}, which has no header form` ); } - const bodyString = mcpParamPrimitiveToString(bodyRaw); - if (bodyString === undefined) { - // A non-finite number or an unsafe integer has no header form; - // params validation owns that fault. Skip the header check. - continue; - } if (headerValue === null) { return paramHeaderMismatchRejection( 'param-header-missing', diff --git a/packages/core-internal/test/shared/mcpParamHeaders.test.ts b/packages/core-internal/test/shared/mcpParamHeaders.test.ts index 88026ca355..d8f00cef9b 100644 --- a/packages/core-internal/test/shared/mcpParamHeaders.test.ts +++ b/packages/core-internal/test/shared/mcpParamHeaders.test.ts @@ -300,9 +300,26 @@ describe('validateMcpParamHeaders — server-behavior table', () => { } }); - test('header absent and the body value is an object → ok (params validation owns it)', () => { + test('header absent and the body value is an object or array → reject 400/-32020 as missing', () => { + for (const region of [{ a: 'eu' }, ['eu']]) { + expect(validateMcpParamHeaders(DECLS, { region }, new Headers())).toMatchObject({ + kind: 'reject', + httpStatus: 400, + code: HEADER_MISMATCH_ERROR_CODE, + cell: 'param-header-missing' + }); + } + }); + + test('unsafe integer body value: a present header is rejected, an absent one passes', () => { const intDecl = [{ path: ['n'], headerName: 'N', type: 'integer' }] as const; - expect(validateMcpParamHeaders(intDecl, { n: { a: 1 } }, new Headers())).toBeUndefined(); + const n = 2 ** 53; + expect(validateMcpParamHeaders(intDecl, { n }, new Headers({ [`${MCP_PARAM_HEADER_PREFIX}N`]: '5' }))).toMatchObject({ + kind: 'reject', + code: HEADER_MISMATCH_ERROR_CODE, + cell: 'param-header-mismatch' + }); + expect(validateMcpParamHeaders(intDecl, { n }, new Headers())).toBeUndefined(); }); test('invalid Base64 sentinel → reject 400/-32020', () => {