MCP TypeScript SDK 2.4.0 Adds Skills Support and OAuth Refresh Scope

What happened

The Model Context Protocol TypeScript SDK released version 2.4.0 with major additions for skills publishing and OAuth compatibility. The release includes a new Skills extension that implements SEP-2640, allowing servers to publish skills that clients can consume with verification and caching support. It also adds an opt-in scope parameter for OAuth token refresh requests to support authorization servers that require it.

Skills extension details

The Skills extension is split into three packages. The server-side @modelcontextprotocol/server/ext/skills exports SkillsExtension, which serves skills/list, skills/get, resources/directory/read endpoints and a skill://{+path} resource template. Servers can load skills from files using loadSkills(folder) or the memorySkillFiles adapter, and configure strict validation or skip invalid skills with a warning. Files are served as UTF-8 text if the bytes are valid, otherwise as base64 blobs.

The client-side @modelcontextprotocol/client/ext/skills provides SkillsClient with list(), get(), read(), and readDirectory() methods. The read() method verifies size and digest fields, and checks SKILL.md frontmatter; if verification fails, it fetches fresh data with cacheMode: 'refresh'. The @modelcontextprotocol/core/ext/skills package provides shared schemas, types, and constants including SKILL_LIMITS.

Skills work on both 2025-11-25 and 2026-07-28 MCP versions. On 2026-07-28, the server sends caching fields (ttlMs, cacheScope) and the client requires and returns them. The SkillsExtension.attach method is marked experimental and may change in a minor release; the rest of the Skills API is stable.

OAuth refresh scope support

A new optional scopeForRefresh(tokens) method on OAuthClientProvider allows sending scope on token refresh requests. This addresses cases where an authorization server rejects refresh requests without scope, such as Microsoft Entra ID (AADSTS90009 error). When implemented, the client includes the returned scope in refresh requests. If the response contains no scope but one was sent, the sent scope is kept on the returned tokens. The default behavior remains unchanged if this option is not implemented.

Breaking changes and spec compliance

The release tightens validation to match the 2026-07-28 MCP spec. The x-mcp-header annotation on number-typed tool parameters is now rejected; clients do not list such tools and servers respond with -32020 when called. Use z.int() or remove the annotation instead. Additionally, outputSchema from z.object(...).meta({ id }) no longer wraps results in { result } on 2025-11-25 connections; read structuredContent directly, not structuredContent.result.

The bundled Ajv validator was updated to fast-uri 3.1.8, which rejects invalid URI schemes in $id or $ref (such as my_tool:output) and invalid URN namespaces (such as urn:my_tool:output). Schemas using these patterns no longer compile, and tools carrying them fail with invalid-schema error. Valid URI schemes and references into #/$defs/ or #/definitions/ are unaffected.

Other fixes and improvements

Resource and resource template updates now appear in list responses when called with update({ title }). Servers connected to per-request transports at a modern revision now bind that revision correctly instead of answering -32022. The createMcpHandler function sends Allow: POST on every 405 response. The @modelcontextprotocol/node package now accepts both @hono/node-server 1.x and 2.x, with new installs resolving to 2.x. ServerEvent gains an optional params field to allow gateways to forward change notifications with their _meta information.

Documentation and tools

The v1 to v2 upgrade guide is now available as an installable agent skill, making migration assistance more accessible within MCP-based environments.

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.