fix(server): keep the Mcp-Param check on a tool with a number-typed header

[claude]

Requested by Felix Weinberger · Slack thread

Follow-up to #2762.

Before: #2762 makes the declaration scan report a tool as invalid when it puts x-mcp-header on a number-typed parameter. createMcpHandler compared the Mcp-Param-* headers with the body only when the scan was valid, so for such a tool the whole check went away, valid string, integer and boolean parameters included: a tools/call whose header disagrees with the body got 200 where released 2.3.0 answers 400 with -32020.

After: The scan keeps walking after a number fault. When those are the tool's only faults it returns the declarations next to the reason, and the handler checks whatever declarations the scan returns. The result is still invalid, so clients still drop the tool from tools/list and the server still warns; registerTool does not throw. Between an upgraded client and an upgraded server, a call by name of such a tool is answered 400 again, as against a 2.3.0 server; with #2762 alone it was 200. A tool with another fault as well was not checked in 2.3.0 and is not checked now.

How it was verified: Against released 2.3.0 over 13 tool shapes and 68 request cases (status, error code, the header named in the error, whether the handler ran), main today differs in 20 cases and this change in 0. The new server test fails without either source change (expected [200, …] to deeply equal [400, -32020, 'Mcp-Param-Region']); the new client test fails as soon as number is permitted again. core-internal, client and server suites pass; typecheck, ESLint, Prettier, sync-snippets --check and docs:check are clean. Changeset: @modelcontextprotocol/server patch.

🤖 Generated with Claude Code

https://claude.ai/code/session_012VRbFCp41otcScXE1YY3es

---

Generated by Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: fbdfbec

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@modelcontextprotocol/server	Patch
@modelcontextprotocol/client	Patch
@modelcontextprotocol/codemod	Patch
@modelcontextprotocol/core	Patch
@modelcontextprotocol/server-legacy	Patch
@modelcontextprotocol/core-internal	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@2960

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@2960

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@2960

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@2960

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@2960

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@2960

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@2960

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@2960

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@2960

commit: fbdfbec

[claude]

Findings marked 🟡 are optional suggestions and need no follow-up push.

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

[claude]

I re-reviewed the latest push and found no bugs; the two docs follow-ups address the points I raised earlier, and the remaining question is a design call rather than a defect, so a maintainer look to confirm the intended client/server contract is still worthwhile.

What was reviewed:

• The reworded changeset against the code: the stdio carve-out matches the early return in client.ts:2557, and "a call that carries a value for a declared parameter" matches validateMcpParamHeaders skipping absent/null body values (mcpParamHeaders.ts:355).
• The scanner's early-return paths once more: a non-number fault still returns without declarations, so the handler gate at createMcpHandler.ts:833 only widens the check for number-only-invalid tools, as the changeset says.
• The remaining design point (server validates a spec-invalid declaration that an upgraded client will never mirror) is now stated in both the changeset and the migration guide, so it is a deliberate, documented choice for the owners to confirm.

Extended reasoning...

The change touches the shared x-mcp-header scanner in core-internal, the tools/call header gate in createMcpHandler, two tests, a changeset and a migration paragraph; the only new commit since my last review is a one-line changeset rewording. It touches request validation (400 / -32020 on Mcp-Param-* mismatch) but no auth, crypto or data-exposure surface. All paths are covered by the repository-wide CODEOWNERS team, and the PR embeds a cross-package behaviour decision (client excludes the tool, server keeps validating it) that a maintainer should confirm, so I deferred rather than approved despite finding no bugs.