Model Context Protocol Release Notes

Minor Changes

• #2501 1480241 Thanks @felixweinberger! - Export the Protocol base class and mergeCapabilities from the @modelcontextprotocol/client and @modelcontextprotocol/server package roots, restoring the v1 import for consumers that subclass Protocol (e.g. the MCP Apps SDK). The client and server packages each bundle their own compiled copy of the class, so import it from one package consistently within a process.
• The codemod now rewrites Protocol and mergeCapabilities imports from shared/protocol.js to the client or server package root, like the module's other symbols, instead of dropping them with an action-required marker.
• #2513 f413763 Thanks @felixweinberger! - Align the 2026-07-28 wire with the final revision (spec PR #3002): serverInfo moves from the DiscoverResult body to the result _meta, and the per-request envelope's clientInfo demotes from required to SHOULD.
• Before this change the SDK shipped the pre-#3002 shape in both directions: the client hard-rejected a conforming server's DiscoverResult (missing body serverInfo failed parse, so the probe misclassified the server as legacy and attempted an initialize handshake against it — a hard connect failure against a modern-only server such as go-sdk v1.7.0-pre.3), and the server rejected conforming clients that omit clientInfo.
• Now:
• The 2026 wire schemas are the final revision exactly: no body serverInfo on DiscoverResult, envelope clientInfo optional (a present-but-malformed value still fails validation).
• Servers stamp _meta['io.modelcontextprotocol/serverInfo'] on every 2026-era response (spec SHOULD; a handler-authored value wins, the 2025-era wire is untouched). This includes the entry-built subscriptions/listen graceful-close results — the spec's SubscriptionsListenResultMeta extends ResultMetaObject.
• Clients keep sending clientInfo and read server identity from the discover result's _meta only. A server that stamps no identity is anonymous: getServerVersion() is undefined and the response cache partitions under a per-connection surrogate. A malformed _meta serverInfo value is treated as absent on receive (the spec marks the field self-reported, unverified, and display-only).
• Breaking type changes: DiscoverResult no longer declares serverInfo; RequestMetaEnvelope's clientInfo is optional. New public constant SERVER_INFO_META_KEY ('io.modelcontextprotocol/serverInfo').

Patch Changes

• Updated dependencies [f413763]:
  • @modelcontextprotocol/[email protected]

Minor Changes

#2513 f413763 Thanks @felixweinberger! - Align the 2026-07-28 wire with the final revision (spec PR #3002): serverInfo moves from the DiscoverResult body to the result _meta, and the per-request envelope's clientInfo demotes from required to SHOULD.

Before this change the SDK shipped the pre-#3002 shape in both directions: the client hard-rejected a conforming server's DiscoverResult (missing body serverInfo failed parse, so the probe misclassified the server as legacy and attempted an initialize handshake against it — a hard connect failure against a modern-only server such as go-sdk v1.7.0-pre.3), and the server rejected conforming clients that omit clientInfo.

Now:

The 2026 wire schemas are the final revision exactly: no body serverInfo on DiscoverResult, envelope clientInfo optional (a present-but-malformed value still fails validation).

Servers stamp _meta['io.modelcontextprotocol/serverInfo'] on every 2026-era response (spec SHOULD; a handler-authored value wins, the 2025-era wire is untouched). This includes the entry-built subscriptions/listen graceful-close results — the spec's SubscriptionsListenResultMeta extends ResultMetaObject.

Clients keep sending clientInfo and read server identity from the discover result's _meta only. A server that stamps no identity is anonymous: getServerVersion() is undefined and the response cache partitions under a per-connection surrogate. A malformed _meta serverInfo value is treated as absent on receive (the spec marks the field self-reported, unverified, and display-only).

Breaking type changes: DiscoverResult no longer declares serverInfo; RequestMetaEnvelope's clientInfo is optional. New public constant SERVER_INFO_META_KEY ('io.modelcontextprotocol/serverInfo').

Patch Changes

#2501 1480241 Thanks @felixweinberger! - Export the Protocol base class and mergeCapabilities from the @modelcontextprotocol/client and @modelcontextprotocol/server package roots, restoring the v1 import for consumers that subclass Protocol (e.g. the MCP Apps SDK). The client and server packages each bundle their own compiled copy of the class, so import it from one package consistently within a process.

The codemod now rewrites Protocol and mergeCapabilities imports from shared/protocol.js to the client or server package root, like the module's other symbols, instead of dropping them with an action-required marker.

Minor Changes

• #2501 1480241 Thanks @felixweinberger! - Export the Protocol base class and mergeCapabilities from the @modelcontextprotocol/client and @modelcontextprotocol/server package roots, restoring the v1 import for consumers that subclass Protocol (e.g. the MCP Apps SDK). The client and server packages each bundle their own compiled copy of the class, so import it from one package consistently within a process.
• The codemod now rewrites Protocol and mergeCapabilities imports from shared/protocol.js to the client or server package root, like the module's other symbols, instead of dropping them with an action-required marker.
• #2511 f60dff0 Thanks @felixweinberger! - ConnectOptions.prior accepts a cached era verdict — the new exported type PriorDiscovery. { kind: 'modern', discover } adopts a previously obtained DiscoverResult with zero round trips; { kind: 'legacy' } skips the server/discover probe and runs the plain initialize handshake directly, for servers known out-of-band to be legacy — without pinning the client to mode: 'legacy': stop supplying the verdict and connect() falls back to the configured versionNegotiation mode (under 'auto', it re-probes and rediscovers an upgraded server). Freshness is the supplying host's responsibility — a stale legacy verdict succeeds silently against an upgraded server, so hosts must date cached legacy verdicts in their own storage and stop supplying them past their policy horizon. Persisted-blob plumbing is hardened: prior: null is treated as absent, the modern arm's discover payload is schema-validated before any connection state changes, and an unrecognized shape rejects with a typed SdkError(EraNegotiationFailed) instead of a TypeError.
• #2513 f413763 Thanks @felixweinberger! - Align the 2026-07-28 wire with the final revision (spec PR #3002): serverInfo moves from the DiscoverResult body to the result _meta, and the per-request envelope's clientInfo demotes from required to SHOULD.
• Before this change the SDK shipped the pre-#3002 shape in both directions: the client hard-rejected a conforming server's DiscoverResult (missing body serverInfo failed parse, so the probe misclassified the server as legacy and attempted an initialize handshake against it — a hard connect failure against a modern-only server such as go-sdk v1.7.0-pre.3), and the server rejected conforming clients that omit clientInfo.
• Now:
• The 2026 wire schemas are the final revision exactly: no body serverInfo on DiscoverResult, envelope clientInfo optional (a present-but-malformed value still fails validation).
• Servers stamp _meta['io.modelcontextprotocol/serverInfo'] on every 2026-era response (spec SHOULD; a handler-authored value wins, the 2025-era wire is untouched). This includes the entry-built subscriptions/listen graceful-close results — the spec's SubscriptionsListenResultMeta extends ResultMetaObject.
• Clients keep sending clientInfo and read server identity from the discover result's _meta only. A server that stamps no identity is anonymous: getServerVersion() is undefined and the response cache partitions under a per-connection surrogate. A malformed _meta serverInfo value is treated as absent on receive (the spec marks the field self-reported, unverified, and display-only).
• Breaking type changes: DiscoverResult no longer declares serverInfo; RequestMetaEnvelope's clientInfo is optional. New public constant SERVER_INFO_META_KEY ('io.modelcontextprotocol/serverInfo').

Patch Changes

• #2514 6fe1963 Thanks @felixweinberger! - Probe stdio servers on a disposable sibling process. Some stdio servers exit on any pre-initialize request (servers built on the official Rust SDK, rmcp, behave this way), so under versionNegotiation: { mode: 'auto' } the server/discover probe previously killed the server and connect() hard-failed. The probe now runs on a short-lived sibling spawned from the same parameters — its stderr is discarded and it is reaped once the era is known — and the caller's transport spawns exactly once, afterwards: a legacy verdict connects with the plain initialize handshake (byte-identical to mode: 'legacy'), a modern verdict is adopted directly, and the session wire never carries server/discover. Closing the caller's transport during the probe aborts connect() with the typed SdkError(EraNegotiationFailed) and the session child is never spawned. On HTTP — and on custom stdio-shaped transports, which probe in place — a mid-probe connection close keeps rejecting with the typed connect error, now naming the close in pin-mode and modern-only diagnostics.
• Updated dependencies [f413763]:
• @modelcontextprotocol/[email protected]

Minor Changes

#2477 8e1d2e9 Thanks @felixweinberger! - Move the schema source modules (spec schemas, OAuth schemas, protocol constants) into @modelcontextprotocol/core and resolve them from there as a regular runtime dependency instead of bundling a private copy into each package. An application importing more than one of the packages now evaluates a single shared schema graph with shared object identity. @modelcontextprotocol/core gains a ./internal subpath (SDK-internal contract; may change in any release) and the four packages now version together.

Patch Changes

#2476 e0a0ab7 Thanks @felixweinberger! - Build protocol-revision wire schemas lazily on first validation instead of at import. Each revision's schema set is now constructed by a module-level memoized factory, so importing the client or server package no longer pays the construction cost of both frozen wire-schema graphs up front. Method membership in the revision registries stays static, the schemas themselves are unchanged, and registry lookups keep returning reference-identical schema objects.

Updated dependencies [8e1d2e9]:

@modelcontextprotocol/[email protected]

Minor Changes

#2477 8e1d2e9 Thanks @felixweinberger! - Move the schema source modules (spec schemas, OAuth schemas, protocol constants) into @modelcontextprotocol/core and resolve them from there as a regular runtime dependency instead of bundling a private copy into each package. An application importing more than one of the packages now evaluates a single shared schema graph with shared object identity. @modelcontextprotocol/core gains a ./internal subpath (SDK-internal contract; may change in any release) and the four packages now version together.

#2483 3f07a32 Thanks @felixweinberger! - Add preloadSchemas(), an explicit opt-in to eager wire-schema construction, and call it automatically in the Cloudflare Workers builds. The wire schemas are built lazily by default, which is the right trade on process-per-invocation runtimes — but on isolate platforms that bill request CPU while module evaluation runs during isolate warm-up, laziness moves construction into the first request each fresh isolate serves. Calling preloadSchemas() at module scope (it is synchronous and idempotent) moves that one-time cost back to module evaluation; the packages' workerd export condition now does this automatically, while the Node and browser builds stay lazy. The server package gains a dedicated browser shim for this (its browser condition previously reused the workerd shim), so browser bundles keep lazy construction.

Patch Changes

#2458 7c49b47 Thanks @felixweinberger! - Construct the default Ajv validation engine lazily on first validation. Creating a Client or Server no longer pays the ajv + ajv-formats instantiation cost at startup when no JSON Schema validation ever runs.

#2476 e0a0ab7 Thanks @felixweinberger! - Build protocol-revision wire schemas lazily on first validation instead of at import. Each revision's schema set is now constructed by a module-level memoized factory, so importing the client or server package no longer pays the construction cost of both frozen wire-schema graphs up front. Method membership in the revision registries stays static, the schemas themselves are unchanged, and registry lookups keep returning reference-identical schema objects.

Updated dependencies [8e1d2e9]:

@modelcontextprotocol/[email protected]