MCP TypeScript SDK 2.4.0 Adds Skills Extension and Spec Compliance Updates

Skills Extension Arrives in MCP

The Model Context Protocol TypeScript SDK now includes a Skills extension, enabling servers to publish skills and clients to discover and verify them. Servers use loadSkills(folder) and skills.attach(server) to expose a folder of skills as resources, with responses including size, digest, and SKILL.md frontmatter. Clients call SkillsClient methods: list() to enumerate available skills with optional skipInvalid handling, get() to retrieve individual skill metadata, read(skill, path?) to fetch skill files with verification, and readDirectory() to explore skill folders.

Skills support both 2025-11-25 and 2026-07-28 protocol revisions. On 2026-07-28 only, the server sends caching fields (ttlMs and cacheScope), which SkillsClient requires and returns from its methods. The API is stable except SkillsExtension.attach, marked experimental, which may change in a future minor release. Skills can skip invalid entries with warnings or fail strictly under strict mode; files with valid UTF-8 bytes are served as text regardless of MIME type, others as base64 blobs.

Breaking Changes for Spec Compliance

Version 2.4.0 tightens conformance to the 2026-07-28 specification. Number parameters annotated with x-mcp-header are now rejected—the client no longer lists such tools and the server responds with error -32020. Developers should use z.int() or remove the annotation. Additionally, outputSchema constructed from z.object(...).meta({id}) no longer wraps results in a { result } object; callers now read structuredContent directly instead of structuredContent.result.

URI validation has become stricter following an upgrade to fast-uri 3.1.8, which rejects $id or $ref with invalid URI schemes such as my_tool:output. These changes align the SDK with spec requirements but require code updates for affected projects.

• Number parameters with x-mcp-header are now rejected; use z.int() instead
• outputSchema from z.object().meta({id}) no longer wraps results—read structuredContent directly
• Invalid URI schemes in $id or $ref are now rejected by the validator

OAuth Scope and Resource Updates

Developers using authorization servers that require scope on token refresh can now implement scopeForRefresh(tokens) on their OAuthClientProvider. This addresses compatibility with services like Microsoft Entra ID that reject refresh requests without scope. The default refresh request remains unchanged, making adoption optional.

ServerEvent now accepts optional params, allowing gateways to forward change notifications with their _meta fields. This enables richer notification tracking across protocol implementations.

Fixes and Package Updates

Several fixes improve reliability. The update({title}) method on resources and resource templates now appears in list responses. A server connected to a per-request transport at a modern revision correctly binds that revision instead of answering -32022. The createMcpHandler function now sends Allow: POST on every 405 response. The @modelcontextprotocol/node package now accepts @hono/node-server 1.x or 2.x; new installations resolve to 2.x.

Core packages advance to 2.4.0: @modelcontextprotocol/client, @modelcontextprotocol/server, @modelcontextprotocol/core, @modelcontextprotocol/server-legacy, and @modelcontextprotocol/codemod. The @modelcontextprotocol/node package stays at 2.1.2. Express, Hono, and Fastify integrations remain unchanged. A v1 to v2 upgrade guide is now available as an installable agent skill.

Compatibility and Migration

The Skills extension supports both active protocol revisions: 2025-11-25 connections can use skills without caching fields, while 2026-07-28 connections receive and require ttlMs and cacheScope. This dual support eases gradual adoption. Developers upgrading should review upgrade notes for the breaking changes, particularly around header validation and output schema structure, and test their tools and servers against the stricter URI validation before deploying.

Source

AI-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.