TL;DR
- Skills over MCP (SEP-2640) let servers publish skill folders that clients can list, read, and verify using SkillsClient, working on recent protocol versions
- OAuth clients can now opt-in to token refresh scope via scopeForRefresh() to handle authorization servers like Microsoft Entra ID that require scope on refresh
- Breaking changes include rejection of x-mcp-header on number parameters, unwrapped outputSchema results on modern connections, and stricter URI validation in the bundled Ajv validator
- Several fixes address resource update visibility, per-request transport revision binding, HTTP handler response headers, and @modelcontextprotocol/node dependency compatibility
- Version
- 2.4.0
- Protocol support
- 2025-11-25 and 2026-07-28 specs
What happened
The Model Context Protocol TypeScript SDK 2.4.0 was released with new capabilities for skills management and OAuth authentication, along with several breaking changes aligned with the protocol specification. The release updates the main packages: @modelcontextprotocol/client, @modelcontextprotocol/server, @modelcontextprotocol/core, @modelcontextprotocol/server-legacy, and @modelcontextprotocol/codemod all reached 2.4.0, while @modelcontextprotocol/node was updated to 2.1.2. Express, Hono, and Fastify integrations remain unchanged.
Skills over MCP arrives
The release introduces Skills over MCP (SEP-2640), enabling servers to publish folders of skills using loadSkills(folder) and skills.attach(server). Clients can list, read, and verify these skills using SkillsClient. The feature works with protocol connections at versions 2025-11-25 and 2026-07-28. Note that the attach method is experimental and may change in a minor release.
OAuth refresh scope handling
Developers can now implement scopeForRefresh(tokens) on their OAuthClientProvider to handle authorization servers that reject token refresh requests without scope—a requirement from systems like Microsoft Entra ID (AADSTS90009). The default refresh request behavior remains unchanged; this is an opt-in feature for those who need it.
Breaking changes require attention
Three breaking changes affect existing code. First, x-mcp-header annotations on number parameters are now rejected as required by the 2026-07-28 spec; the server responds with error -32020. Use z.int() or remove the annotation instead. Second, outputSchema from z.object(...).meta({ id }) behaves differently on 2025-11-25 connections: the result is no longer wrapped in { result }, so code should read structuredContent directly rather than structuredContent.result. Third, the bundled Ajv validator (using fast-uri 3.1.8) now rejects $id or $ref with invalid URI schemes, such as my_tool:output.
Other improvements
ServerEvent now accepts optional params, allowing gateways to forward change notifications with their _meta field. The v1 to v2 upgrade guide is now available as an installable agent skill. Fixes include: resource or resource template update({ title }) calls now appear in list responses; a Server connected to a per-request transport at a modern revision now binds that revision instead of responding with -32022; createMcpHandler now sends Allow: POST on every 405 response; and @modelcontextprotocol/node now accepts both @hono/node-server 1.x and 2.x, with new installs resolving to 2.x.
Check before upgrading
- x-mcp-header on number parameters is rejected per the 2026-07-28 spec; use z.int() or remove the annotation
- outputSchema from z.object(...).meta({ id }) no longer wraps the result in { result } on 2025-11-25 connections; read structuredContent directly
- Bundled Ajv validator (fast-uri 3.1.8) rejects $id or $ref with invalid URI schemes
Source
MCP TypeScript SDK Releaseshttps://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.4.0AI-assisted, verified against the source. This post was drafted with AI from the primary source linked above and checked automatically against it. For anything you depend on, read the original.
- #modelcontextprotocol
- #typescript
- #skills
- #oauth
- #sdk
