MCP TypeScript SDK v2.2.0

What it claims

v2.2.0 changes two behaviours that existing callers will notice: machine-to-machine OAuth providers now check which authorization server they are bound to, and the list methods now return complete lists. It also fixes a CommonJS type-checking break that 2.1.0 introduced, along with several promise-rejection and handler bugs.

How to use it

Upgrade checklist, as the notes state it:

• Add expectedIssuer to every ClientCredentialsProvider, PrivateKeyJwtProvider, StaticPrivateKeyJwtProvider and CrossAppAccessProvider. Set it to the issuer of the authorization server the credentials were registered with. Leaving it out is now deprecated and logs a warning. It is not an error yet.
• Expect AuthorizationServerMismatchError from fetchToken(). It is thrown before any request is sent when the stored client information belongs to a different authorization server. Handle it wherever you call fetchToken().
• Custom token or client storage: OAuthTokensSchema and OAuthClientInformationSchema now accept an optional issuer field. A provider that reads its storage back through these schemas keeps the binding. Storage that bypasses them may lose it. Check yours.
• List calls: listTools(), listPrompts(), listResources() and listResourceTemplates() called without a cursor now keep following nextCursor until the server stops sending one. listMaxPages still limits the walk. Review code that assumed a cursor-less call returns only the first page.
• createMcpHandler: the stack overflow when the factory reuses a server instance is fixed. The notes say returning a fresh instance per request is still required, so the fix does not make reuse supported.

Fixes worth knowing if you hit them

• CommonJS TypeScript projects: these failed to type-check in 2.1.0 because of the jose types used by the DPoP API. 2.2.0 inlines those types into the declaration files. CJS users on 2.1.0 should upgrade.
• Client.listen(): it no longer leaks a process-level unhandled rejection. It also no longer hangs when a send never settles.
• Closed connections: sending a notification on a closed connection no longer causes a brief unhandled rejection.
• _meta: it is now preserved on input_required results.
• subscriptions/listen: createMcpHandler now ends the stream immediately after the acknowledgement if it honoured none of the requested notification types.
• Local OAuth setups: *.localhost hostnames now count as loopback for OAuth token endpoints. This enables host-based multi-tenant local setups.
• v1-to-v2 codemod: it now keeps leading comment blocks and directives above the rewritten imports.

Limits

The page is release notes only. It gives no migration examples, no default value for listMaxPages, and no date for when a missing expectedIssuer becomes a hard error. Details are in the per-package changelogs (client, server, core, server-legacy, codemod) and the linked PRs (#2887, #2886, #2883).