// 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
ACTION NEEDED MIGRATE APIDEPRECATION
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 verdictMATERIAL at 0.92, needed 0.5
triage reasoningMultiple breaking API changes, new MCP features, and spec-tied behavioral shifts require engineering attention.
signalsbreaking 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 modelanthropic/claude-haiku-4.5 ($0.00000)
writer modelanthropic/claude-sonnet-4.5 ($0.00000)