// AI Platform Drift

MCP TypeScript SDK 2.4.0 rejects number-typed tool parameters with headers

MCP TypeScript SDK releases · published 2026-10-24 04:40 UTC
ACTION NEEDED MIGRATE APIDEPRECATION
WHAT CHANGEDVersion 2.4.0 of @modelcontextprotocol/server now rejects tools that use x-mcp-header on number-typed parameters, returning error -32020. On 2026-07-28 protocol connections (non-stdio), clients no longer list such tools and reject calls with declared parameter values. The bundled Ajv validator (fast-uri 3.1.8) now rejects schemas with invalid URI schemes in $id or $ref (e.g., my_tool:output, urn:my_tool:output); underscores without colons and #/$defs references are unaffected. Tool outputSchema handling changed: schemas with root $ref to type: "object" definitions no longer wrap results in { result: ... } on 2025-era connections.
WHY IT MATTERSTools with number-typed parameters annotated with x-mcp-header will fail validation and be excluded from tool listings on modern protocol versions. Existing schemas using underscores in identifiers before colons will fail compilation, breaking tools that depend on them. Clients reading structuredContent.result for tools with object-ref output schemas will receive malformed data on 2025 connections.
WHAT TO DOAudit tool definitions for x-mcp-header on number-typed parameters; change to integer (z.int()) or remove the annotation. Search schemas for $id and $ref values containing underscores or custom prefixes before colons (pattern: [a-z_]+:); replace with valid URI schemes or move identifiers after the fragment (#/). For tools with outputSchema root $refs to object definitions, update 2025-era clients to read structuredContent directly instead of structuredContent.result.
ACT-BY DATE PASSED — this item's act-by date, 2026-07-28, is before this page was generated 2026-11-21 (UTC). Check the primary source before acting on it.
Model-reported confidence 85% (not measured accuracy) Primary source ↗ written by anthropic/claude-sonnet-4.5
Show the reasoning — raw diff, triage verdict, confidence
RAW DIFF
+## @modelcontextprotocol/server@2.4.0
+https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol%2Fserver%402.4.0
+2026-10-23T18:19:14Z
+
+Minor Changes
+
+#3057 c05225a Thanks @steipete! - ServerEvent takes optional params, which the subscriptions/listen router delivers with its own subscription ID, so a gateway can forward change notifications with their _meta and extension params.
+
+#3047 46d9c99 Thanks @KKonstantinov, @tobi-oye, @mattzcarey! - Add the Skills extension (SEP-2640), reachable through new ext/skills subpaths; package root exports are unchanged.
+
+@modelcontextprotocol/server/ext/skills: SkillsExtension (attach(server) serves skills/list, skills/get, resources/directory/read and a skill://{+path} resource template), SkillsExtension.load(files) returning a SkillCatalog with entries and reload(), the SkillFiles storage adapter with memorySkillFiles, SkillSource for generated catalogs, skillEntry, and SkillCatalogError. Invalid skills are skipped with a warning (onWarning), or fail under strict. A file whose bytes are valid UTF-8 is served as text, whatever its MIME type; any other file as a base64 blob.
+@modelcontextprotocol/server/ext/skills/node: loadSkills(folder) and nodeSkillFiles(folder).
+@modelcontextprotocol/client/ext/skills: SkillsClient with list() (throws on an invalid entry; skipInvalid: true keeps the valid ones and returns the rest in invalid), get(), read(skill, path?) (size, digest and SKILL.md frontmatter verified, SkillVerificationError on a mismatch; a copy from the response cache that fails a check is fetched once more with cacheMode: 'refresh' first) and readDirectory().
+@modelcontextprotocol/core/ext/skills: schemas, types and constants, including SKILL_LIMITS. The result schemas follow the stable spec, so ttlMs and cacheScope are required.
+
+SkillsExtension.attach is @experimental: how an extension is wired to a server may change in a minor release. The rest of the Skills API is stable.
+Works on 2025-11-25 and 2026-07-28. On 2026-07-28 only, the server sends the caching fields (ttlMs, cacheScope), and SkillsClient requires them and returns them from list(), get() and readDirectory().
+
+Patch Changes
+
+#3083 ef38c67 Thanks @claude! - The bundled Ajv validator is now built with fast-uri 3.1.8 (was 3.1.0). fast-uri 3.1.6 and later reject a $id or $ref whose text before the first colon is not a valid URI scheme (my_tool:output), or whose URN namespace is not valid (urn:my_tool:output): a schema that uses one no longer compiles, and a tool that carries it fails with an invalid-schema error. An underscore without a colon (my_tool_output) and a $ref into #/$defs/... or #/definitions/... are not affected.
+
+#2960 43c45f4 Thanks @claude! - A server whose tool puts x-mcp-header on a number-typed parameter keeps checking that tool's Mcp-Param-* headers on tools/call, as 2.3.0 does: a header that is missing for a value in the body, or that disagrees with the body, is answered 400 with JSON-RPC error -32020. Clients on a 2026-07-28 connection other than stdio no longer list such a tool and send no Mcp-Param-* headers for it, so a call that carries a value for a declared parameter is rejected the same way; the server logs a warning each time tools are listed. Use an integer (z.int()) or remove the annotation.
+
+#3081 5820f79 Thanks @claude! - A tool outputSchema whose root is a $ref to a type: "object" entry of its own $defs or definitions (what zod writes for z.object({...}).meta({ id })), or a union of such refs, is now treated as an object schema. On 2025-era connections the tool's schema and structuredContent are no longer wrapped in { result: ... }, so a 2025-era client that read structuredContent.result for such a tool now reads structuredContent. On every era the advertised schema gains type: "object" at its root.
+
+#3057 c05225a Thanks @steipete! - Connecting a Server or McpServer to a PerRequestHTTPServerTransport classified at a modern revision that supportedProtocolVersions lists and the SDK implements now binds that revision, instead of answering -32022.
+
+#3005 b381559 Thanks @chaeyn! - Reflect resource and resource template update({ title }) changes in list responses. Preserve other metadata and individual resource titles when a template supplies list entries.
+
+#3002 895007f Thanks @Hugo-DDT! - createMcpHandler now sends Allow: POST on every 405 it answers to a non-POST request, with legacy: 'stateless' (the default) and with legacy: 'reject'.
+
+#2762 b022522 Thanks @pcarleton! - x-mcp-header on a number-typed tool parameter is now rejected, matching the 2026-07-28 spec ("Parameters with type number are not permitted"; clients MUST exclude such tools from tools/list). Previously number was accepted only to satisfy an older conformance fixture that has since been corrected. integer, string and boolean are unaffected.
+
+Updated dependencies [46d9c99]:
+
+@modelcontextprotocol/core@2.4.0
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 reasoningNew Skills extension, breaking parameter type rejection, and protocol version changes affect API surface and tool compatibility.
signalsnew extension (Skills) added to SDK · breaking change: number-typed tool parameters now rejected · protocol version binding change (HTTP transport) · schema handling change affecting tool output · future date dependency: 2026-07-28 spec alignment · caching field requirement change on future date · validator upgrade with URI scheme validation impact
suppression—
triage modelanthropic/claude-haiku-4.5 ($0.00000)
writer modelanthropic/claude-sonnet-4.5 ($0.00000)