MCP TypeScript SDK 2.4.0
MCP TypeScript SDK 2.4.0 introduces experimental Skills over MCP support, adds opt-in scope handling for OAuth token refreshes, and enforces stricter schema validation rules.
Why this signal matters
MCP TypeScript SDK version 2.4.0 has been released across multiple core packages (@modelcontextprotocol/client, server, core, server-legacy, codemod). Key additions include experimental support for Skills over MCP (SEP-2640) enabling skill publishing and verification via SkillsClient, opt-in scope handling during token refresh via OAuthClientProvider.scopeForRefresh(), and optional params on ServerEvent. The release enforces specification-aligned breaking behaviors: rejection of 'x-mcp-header' on number parameters, unwrapping of outputSchema results on 2025-11-25 connections, and stricter Ajv URI scheme validation under fast-uri 3.1.8.
Actionable summary
Upgrade to MCP TypeScript SDK 2.4.0. Note breaking validation updates: 'x-mcp-header' on number parameters is rejected (error -32020), outputSchema on 2025-11-25 connections unwraps '{ result }' to 'structuredContent', and Ajv via fast-uri rejects invalid URI schemes in '$id' or '$ref'. Experimental Skills support is added via SEP-2640.
- Agent usefulness
- 77/100
- Confidence
- 96%
- Canonical data
- JSON + Markdown
What builders should check
- Replace number parameters using 'x-mcp-header' with 'z.int()' or remove the annotation to prevent -32020 server errors and client filtering.
- Update client-side parsing for outputSchema on 2025-11-25 connections to access 'structuredContent' directly instead of 'structuredContent.result'.
- Ensure all schema '$id' and '$ref' values contain valid URI schemes to satisfy fast-uri 3.1.8 validation.
- Implement 'scopeForRefresh(tokens)' on OAuthClientProvider if integrating with authorization servers like Microsoft Entra ID that mandate scopes on refresh requests.