Model Context Protocol TypeScript SDK 2.4.0 Adds Skills Extension

What happened

The Model Context Protocol TypeScript SDK released version 2.4.0, introducing a Skills extension and updating validation rules. This release includes new APIs for servers to publish and clients to consume skills, alongside compatibility fixes and breaking changes to align with the 2026-07-28 protocol specification.

Skills extension for protocol-native tooling

The Skills extension (SEP-2640) adds first-class support for publishing and discovering reusable tools. Servers can load skills from a folder using loadSkills(folder) and attach them via SkillsExtension.attach(server), which serves skills/list, skills/get, resources/directory/read, and a skill://{+path} resource template. The SkillsExtension class also offers load(files) to return a SkillCatalog with entries and reload() capabilities, plus a SkillFiles storage adapter with a memorySkillFiles implementation.

On the client side, SkillsClient provides list(), get(), read(skill, path?), and readDirectory() methods. The read() method verifies skill size, digest, and SKILL.md frontmatter, throwing SkillVerificationError on mismatch; clients can use cacheMode: 'refresh' to bypass cache if verification fails. Invalid skills are skipped with a warning by default, or can be collected with skipInvalid: true for inspection.

The Skills API works on both 2025-11-25 and 2026-07-28 protocol versions. On 2026-07-28 only, the server sends caching fields (ttlMs, cacheScope), which SkillsClient requires and returns. The SkillsExtension.attach mechanism is marked @experimental and may change in a minor release; the rest of the Skills API is stable. Node.js-specific helpers loadSkills(folder) and nodeSkillFiles(folder) are available under @modelcontextprotocol/server/ext/skills/node.

Validator and parameter changes

The bundled Ajv validator now uses fast-uri 3.1.8 (upgraded from 3.1.0). This version enforces RFC compliance by rejecting $id or $ref where the text before the first colon is not a valid URI scheme (for example, my_tool:output) or where the URN namespace is not valid (urn:my_tool:output). Schemas using invalid schemes no longer compile, and tools carrying them fail with an invalid-schema error. Underscores without colons (my_tool_output) and refs into #/$defs/... or #/definitions/... are unaffected.

Tool parameters typed as number with x-mcp-header annotation are now rejected, matching the 2026-07-28 specification. Clients no longer list such tools, and servers answer calls to them with JSON-RPC error -32020. Developers should use z.int() or remove the annotation. This change corrects an earlier acceptance that was only needed to satisfy an older conformance fixture.

Breaking changes to schema wrapping

The outputSchema handling changes for schemas defined with z.object({...}).meta({ id }). On 2025-11-25 connections, the tool's result is no longer wrapped in { result: ... }, so clients that previously read structuredContent.result must now read structuredContent directly. On all protocol versions, the advertised schema gains type: "object" at its root.

ServerEvent now takes optional params, allowing gateways to forward change notifications with their _meta and extension params, each with its own subscription ID.

Other fixes and updates

Servers connected to a per-request HTTP transport at a modern protocol revision now correctly bind that revision instead of answering -32022. Resource and resource template title updates via update({ title }) are now reflected in list responses, while preserving other metadata. The createMcpHandler now sends Allow: POST on every 405 response to non-POST requests, both with the default legacy: 'stateless' and with legacy: 'reject' modes.

An opt-in scopeForRefresh(tokens) callback is available on OAuthClientProvider for authorization servers requiring scope on token refresh (such as Microsoft Entra ID with AADSTS90009); the default request behavior is unchanged. The @modelcontextprotocol/node package now accepts @hono/node-server 1.x or 2.x, with new installs resolving to 2.x.

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.