// AI Platform Drift
MCP TypeScript SDK 2.4.0 rejects x-mcp-header on number parameters
MCP TypeScript SDK releases · published 2026-10-24 04:40 UTC
WHAT CHANGEDMCP TypeScript SDK 2.4.0, released 2026-10-23, enforces the 2026-07-28 spec requirement that x-mcp-header on number parameters is invalid. The client will not list such a tool, and the server returns error -32020 when called. Additionally, on 2025-11-25 connections, outputSchema results are no longer wrapped: read structuredContent directly instead of structuredContent.result. The bundled Ajv validator now rejects invalid URI schemes in $id or $ref fields, such as my_tool:output.
WHY IT MATTERSExisting tools with x-mcp-header on number parameters will stop appearing in client tool lists and return errors when invoked. Code reading outputSchema results through a .result wrapper will break on 2025-11-25 connections. Schemas using non-standard URI schemes in identifiers will fail validation.
WHAT TO DOAudit tool definitions for x-mcp-header on number parameters and replace with z.int() or remove the annotation. Update outputSchema result handling to read the top-level object instead of .result for 2025-11-25 connections. Check schema $id and $ref fields for invalid URI schemes and replace with valid URIs.
Model-reported confidence 95% (not measured accuracy)
Primary source ↗
written by anthropic/claude-sonnet-4.5
Show the reasoning — raw diff, triage verdict, confidence
RAW DIFF
+## 2.4.0 +https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.4.0 +2026-10-23T18:32:25Z + +Package +Version + +@modelcontextprotocol/client +2.4.0 + +@modelcontextprotocol/server +2.4.0 + +@modelcontextprotocol/core +2.4.0 + +@modelcontextprotocol/server-legacy +2.4.0 + +@modelcontextprotocol/codemod +2.4.0 + +@modelcontextprotocol/node +2.1.2 + +@modelcontextprotocol/express, hono, fastify +unchanged + +Upgrade notes + +x-mcp-header on a number parameter is rejected, as the 2026-07-28 spec requires: the client does not list such a tool, and the server answers a call to it with -32020. Use z.int() or remove the annotation. (#2762, #2960) +outputSchema from z.object(...).meta({ id }). On a 2025-11-25 connection the result is no longer wrapped in { result }: read structuredContent, not structuredContent.result. (#3081) +The bundled Ajv validator uses fast-uri 3.1.8. It rejects a $id or $ref with an invalid URI scheme, such as my_tool:output. (#3083) + +New + +Skills over MCP (SEP-2640). A server publishes a folder of skills with loadSkills(folder) and skills.attach(server); a client lists, reads and verifies them with SkillsClient. It works on 2025-11-25 and 2026-07-28. attach is experimental and may change in a minor release. (#3047, #3080) +Opt-in scope on token refresh. Implement scopeForRefresh(tokens) on your OAuthClientProvider for an authorization server that rejects a refresh without scope (Microsoft Entra ID, AADSTS90009). The default request does not change. (#3085) +ServerEvent takes optional params, so a gateway can forward change notifications with their _meta. (#3057) +The v1 to v2 upgrade guide is also an installable agent skill. (#2968) + +Fixes + +update({ title }) on a resource or resource template shows up in list responses. (#3005) +A Server connected to a per-request transport at a modern revision binds that revision instead of answering -32022. (#3057) +createMcpHandler sends Allow: POST on every 405. (#3002) +@modelcontextprotocol/node accepts @hono/node-server 1.x or 2.x; a new install resolves 2.x. (#3084)
HOW IT WAS JUDGED
Triage signals below are model-reported assertions, preserved verbatim; they are not independent arithmetic verification.
| triage verdict | MATERIAL at 0.92, needed 0.5 |
|---|---|
| triage reasoning | Multiple breaking API changes, new MCP features, and spec-tied behavioral shifts require engineering attention. |
| signals | breaking API change: x-mcp-header on number parameters now rejected per spec · breaking API change: outputSchema result wrapping removed on 2025-11-25 connections · breaking API change: Ajv validator now rejects invalid URI schemes in $id/$ref · new feature: Skills over MCP (SEP-2640) with experimental attach() API · new feature: opt-in scope on token refresh for OAuth providers · spec compliance date: 2026-07-28 referenced as enforcement point · spec compliance date: 2025-11-25 connection behavior change · version bump: multiple packages to 2.4.0, @modelcontextprotocol/node to 2.1.2 |
| suppression | — |
| triage model | anthropic/claude-haiku-4.5 ($0.00000) |
| writer model | anthropic/claude-sonnet-4.5 ($0.00000) |