modelcontextprotocol/typescript-sdk v2.4.0

2.4.0

on GitHub

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)