fix(server): reject Mcp-Param values the header check cannot verify

.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 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.

packages/core-internal/src/shared/mcpParamHeaders.ts

@@ -356,11 +356,29 @@ 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') {
+            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) {
-            // Body carries a non-primitive where the schema declares one;
-            // params validation owns that fault. Skip the header check.
-            continue;
+            // 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 cannot be compared with ${pathName(decl.path)}=${JSON.stringify(bodyRaw)}, which has no header form`
+            );
         }
         if (headerValue === null) {
             return paramHeaderMismatchRejection(

packages/core-internal/test/shared/mcpParamHeaders.test.ts

@@ -287,6 +287,41 @@ 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 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;
+        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', () => {
         const r = validateMcpParamHeaders(
             DECLS,

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?=' }));