Model Context Protocol Release Notes

Package	Version
@modelcontextprotocol/client	2.3.1
@modelcontextprotocol/server	2.3.1
@modelcontextprotocol/core	2.3.1
@modelcontextprotocol/server-legacy	2.3.1
@modelcontextprotocol/codemod	2.3.1
@modelcontextprotocol/node, express, hono, fastify	unchanged

Changes

• requireBearerAuth in @modelcontextprotocol/server-legacy takes the optional expectedResource that @modelcontextprotocol/server 2.3.0 added: it accepts only tokens issued for this server (the token's audience). Off unless you set it. (#2952)
• The npm pages of @modelcontextprotocol/server and @modelcontextprotocol/client now open with one note that links the documentation, the migration guide and the issue form. (#2955)

What's Changed

• [v1.x] docs: state the principles in CLAUDE.md by @claude[bot] in https://github.com/modelcontextprotocol/typescript-sdk/pull/2939
• [v1.x] docs: point the README at v2 and say what v1.x supports by @claude[bot] in https://github.com/modelcontextprotocol/typescript-sdk/pull/2942
• chore: bump version to 1.32.1 by @claude[bot] in https://github.com/modelcontextprotocol/typescript-sdk/pull/2954

Full Changelog: https://github.com/modelcontextprotocol/typescript-sdk/compare/1.32.0...1.32.1

Patch Changes

• #2952 5a18673 Thanks @claude! - requireBearerAuth in @modelcontextprotocol/server-legacy takes the optional expectedResource that @modelcontextprotocol/server 2.3.0 and @modelcontextprotocol/sdk 1.32.0 added: the resource the token must be issued for (its audience), usually the server's URL. When it is set, a token is accepted only if the verifier reports that value in AuthInfo.resource; the two are compared as strings, ignoring a fragment and one trailing slash. A token reported for another value, or for none, is answered 401 invalid_token with the usual WWW-Authenticate challenge. When it is not set, nothing changes. The package stays frozen otherwise; this option is added so that its requireBearerAuth matches the 1.x middleware it is a copy of.

• Updated dependencies []:

  • @modelcontextprotocol/core@2.3.1

pip install -U mcp. Docs: https://py.sdk.modelcontextprotocol.io/

Mostly fixes, plus three new options. A few things behave differently, so skim these first:

Behaviour changes

httpx2>=2.10.0 is now required (#3600)

• It was >=2.5.0. The new max_sse_event_size option needs it.
• Nothing to do unless you pin httpx2 below 2.10.

A tool with an invalid x-mcp-header annotation fails at registration (#3620)

• @mcp.tool(), add_tool and Tool.from_function raise InvalidSignature, naming the tool and the problem.
• Until now the server started, and 2026-07-28 clients silently dropped the tool from their listing.
• Refused: anything other than a plain str, int or bool parameter (so also str | None, float, lists and enums), a header name that isn't a valid token, and two names that differ only by case.
• For an optional header parameter, give the schema directly: Annotated[str | None, WithJsonSchema({"type": "string", "x-mcp-header": "Region"})] = None.

Empty _meta and params are no longer sent (#3628)

• On 2025-11-25 and earlier connections, 2.x sent "_meta": {} on every request. Some servers reject that. It is now left out, as in v1.
• ping and list requests without a cursor go out with no params member.
• On the receiving side ctx.meta is None rather than {}, and middleware sees ctx.params as None for a request without params.
• 2026-07-28 connections are unchanged. …

Package	Version
@modelcontextprotocol/client	2.3.0
@modelcontextprotocol/server	2.3.0
@modelcontextprotocol/core	2.3.0
@modelcontextprotocol/server-legacy	2.3.0
@modelcontextprotocol/codemod	2.3.0
@modelcontextprotocol/node	2.1.1
@modelcontextprotocol/express, hono	2.0.2
@modelcontextprotocol/fastify	2.0.1

Upgrade notes

• One server per request. Server.connect() now rejects while the instance is already connected, and a stateless Streamable HTTP transport handles one request. Create the McpServer and the transport inside the request handler (or in the createMcpHandler factory) instead of sharing one instance across requests. Creating a server is cheap since #2889. (#2918)
• Redirects stay on the same origin. The HTTP client transports now follow a redirect only when it stays on the same origin (same scheme, host and port; http to https on the same host is allowed). A deployment whose endpoint redirects to another host or port either configures the final URL or sets redirectPolicy: 'follow' on the transport. In browsers, a redirected request fails unless that option is set. (#2901) …

Upgrade notes

• Redirects: the HTTP client transports now follow a redirect only when it stays on the same origin (same scheme, host and port; http to https on the same host is allowed). A deployment whose endpoint redirects to another host or port either configures the final URL or sets redirectPolicy: 'follow' on StreamableHTTPClientTransport or SSEClientTransport. In browsers, a redirected request fails unless that option is set.
• New options, both off unless you set them: maxToolInputElements on McpServer limits the number of array elements and object members in a tool call's arguments. expectedResource on requireBearerAuth accepts only tokens issued for this server (the token's audience).

What's Changed

• [v1.x] fix(client): follow redirects only within the endpoint's origin by @claude[bot] in https://github.com/modelcontextprotocol/typescript-sdk/pull/2902
• docs: point SECURITY.md at GitHub Security Advisories (v1.x) by @claude[bot] in https://github.com/modelcontextprotocol/typescript-sdk/pull/2910
• [v1.x] examples: close idle sessions and cap the session map by @maxisbey in https://github.com/modelcontextprotocol/typescript-sdk/pull/2914
• [v1.x] fix(tasks): keep tasks of the in-memory task store within the session that created them by @claude[bot] in https://github.com/modelcontextprotocol/typescript-sdk/pull/2925 …

Minor Changes

• #2929 40f8f4e Thanks @claude! - requireBearerAuth and verifyBearerToken take a new optional expectedResource, which makes them accept only tokens issued for this resource (the token's audience). Set it to the value your authorization server puts into tokens meant for this server, usually the server's URL. When it is set, a token is accepted only if the verifier reports that value in AuthInfo.resource; the two are compared as strings, ignoring a fragment and one trailing slash. A token reported for another value, or for none, is answered 401 invalid_token with the usual WWW-Authenticate challenge. When it is not set, nothing changes. To use it, pass expectedResource and have verifyAccessToken fill AuthInfo.resource, for example from the aud claim. The option is declared on a new exported type, VerifyBearerTokenOptions, which extends BearerAuthOptions; BearerAuthOptions itself is unchanged. The Express requireBearerAuth passes the option through. With Express, @modelcontextprotocol/express has to be upgraded to this release as well: 2.0.1 does not pass the option on, so nothing is compared. Its options type does not have the option, so TypeScript reports an expectedResource written in a call to the 2.0.1 `requireBearerA…

Patch Changes

• #2908 633dd3e Thanks @claude! - The license field of the package manifests is now Apache-2.0; the LICENSE file shipped in each package carries the full terms, including the MIT text for earlier contributions. No code change.

• Updated dependencies [633dd3e]:

  • @modelcontextprotocol/core@2.3.0

Patch Changes

• #2897 7f4c12a Thanks @claude! - hono is now a regular dependency of @modelcontextprotocol/node, so installs with strict peer-dependency checking no longer fail on the hono peer that @hono/node-server requires. No runtime change.

• #2918 84804c2 Thanks @claude! - A Server or McpServer now serves one connection at a time, and a Streamable HTTP server transport without sessions (sessionIdGenerator: undefined) serves one request. An app that uses one server object, or one stateless transport, for every HTTP request fails on the second request after this upgrade. Build the server and the transport per request instead.

  What keeps working without a change:

  • createMcpHandler(buildServer) and serveStdio(buildServer), where buildServer returns a new server on every call.
  • A handler that builds a new server and a new stateless transport for each request.
  • One server and one transport per session (a transport with a sessionIdGenerator).
  • Connecting a server again after close().
  • Client. …

Patch Changes

• #2918 84804c2 Thanks @claude! - A Server or McpServer now serves one connection at a time, and a Streamable HTTP server transport without sessions (sessionIdGenerator: undefined) serves one request. An app that uses one server object, or one stateless transport, for every HTTP request fails on the second request after this upgrade. Build the server and the transport per request instead.

  What keeps working without a change:

  • createMcpHandler(buildServer) and serveStdio(buildServer), where buildServer returns a new server on every call.
  • A handler that builds a new server and a new stateless transport for each request.
  • One server and one transport per session (a transport with a sessionIdGenerator).
  • Connecting a server again after close().
  • Client.

  What fails now, how it shows, and what to change: …

Patch Changes

• #2918 84804c2 Thanks @claude! - A Server or McpServer now serves one connection at a time, and a Streamable HTTP server transport without sessions (sessionIdGenerator: undefined) serves one request. An app that uses one server object, or one stateless transport, for every HTTP request fails on the second request after this upgrade. Build the server and the transport per request instead.

  What keeps working without a change:

  • createMcpHandler(buildServer) and serveStdio(buildServer), where buildServer returns a new server on every call.
  • A handler that builds a new server and a new stateless transport for each request.
  • One server and one transport per session (a transport with a sessionIdGenerator).
  • Connecting a server again after close().
  • Client.

  What fails now, how it shows, and what to change: …

Patch Changes

• #2929 40f8f4e Thanks @claude! - requireBearerAuth and verifyBearerToken take a new optional expectedResource, which makes them accept only tokens issued for this resource (the token's audience). Set it to the value your authorization server puts into tokens meant for this server, usually the server's URL. When it is set, a token is accepted only if the verifier reports that value in AuthInfo.resource; the two are compared as strings, ignoring a fragment and one trailing slash. A token reported for another value, or for none, is answered 401 invalid_token with the usual WWW-Authenticate challenge. When it is not set, nothing changes. To use it, pass expectedResource and have verifyAccessToken fill AuthInfo.resource, for example from the aud claim. The option is declared on a new exported type, VerifyBearerTokenOptions, which extends BearerAuthOptions; BearerAuthOptions itself is unchanged. The Express requireBearerAuth passes the option through. With Express, @modelcontextprotocol/express has to be upgraded to this release as well: 2.0.1 does not pass the option on, so nothing is compared. Its options type does not have the option, so TypeScript reports an expectedResource written in a call to the 2.0.1 `requireBearerA…

Minor Changes

• #2901 433eb41 Thanks @claude! - The HTTP client transports and the OAuth client helpers now follow a redirect only when it stays within the origin of the request (same scheme, host and port, or http to https on the same host with default ports) and keeps the method (a 307 or 308, or any redirect of a GET). Any other redirect is not followed. A transport then fails the request with an error that names the target; the session is kept and later messages still send. OAuth metadata discovery moves on to the next well-known URL, and any other OAuth request fails with an error that gives the status. Same-origin redirects that keep the method keep working on Node, up to five in a row, and no code changes are needed there. If your endpoint redirects to another origin, configure the transport with the URL it redirects to. A requestInit.redirect of 'error' or 'manual' is passed to fetch as it is for the requests a transport sends to the server (POST, GET and DELETE of the Streamable HTTP transport, POST of the SSE transport); for its OAuth requests, and for any other value, requestInit.redirect is not consulted by default. Browsers do not expose the target of a redirect to a page, so there a redirected request fails instead of being followed. Setting `…

Package	Version
@modelcontextprotocol/client	2.2.0
@modelcontextprotocol/server	2.2.0
@modelcontextprotocol/core	2.2.0
@modelcontextprotocol/server-legacy	2.2.0
@modelcontextprotocol/codemod	2.2.0
@modelcontextprotocol/node, express, hono, fastify	unchanged

Upgrade notes

• Pass expectedIssuer to the machine-to-machine OAuth providers. Constructing ClientCredentialsProvider, PrivateKeyJwtProvider, StaticPrivateKeyJwtProvider or CrossAppAccessProvider without it is deprecated and logs a warning. Set it to the issuer of the authorization server the credentials were registered with. (#2887)
• fetchToken() checks which authorization server the client information belongs to. It throws AuthorizationServerMismatchError before sending anything when the provider's client information is bound to a different authorization server. (#2887)
• List calls return the whole list. listTools(), listPrompts(), listResources() and listResourceTemplates() called without a cursor now follow nextCursor until the server stops sending one. listMaxPages still caps the walk. (#2886)

Fixes

• CommonJS TypeScript projects type-check again: the jose types used by the DPoP API are inlined into the declaration files (regression in 2.1.0). (#2883) …

Upgrade notes

• Stored OAuth tokens and client information now include an issuer field. Storage that rejects unknown fields needs to allow it.
• Pass expectedIssuer when constructing ClientCredentialsProvider, PrivateKeyJwtProvider or StaticPrivateKeyJwtProvider. Constructing them without it is deprecated.

What's Changed

• [v1.x] Bind stored OAuth credentials to the authorization server that issued them by @maxisbey in https://github.com/modelcontextprotocol/typescript-sdk/pull/2888
• chore: bump version to 1.31.0 by @claude[bot] in https://github.com/modelcontextprotocol/typescript-sdk/pull/2890

Full Changelog: https://github.com/modelcontextprotocol/typescript-sdk/compare/1.30.1...1.31.0

Patch Changes

• #2885 9dd722f Thanks @claude! - Sending a notification on a closed connection no longer produces a briefly unhandled promise rejection (seen as unhandledrejection on Cloudflare Workers) in addition to the returned rejection.

• #2778 e3fb9ed Thanks @vjymisal0! - Fix a stack overflow in createMcpHandler when the factory returns the same server instance for more than one request. Returning a fresh instance per request is still required.

• #2651 c55efa6 Thanks @sushantkumar23! - createMcpHandler now ends a subscriptions/listen stream right after the acknowledgement when it honored none of the requested notification types, instead of holding the stream open with nothing to deliver. The client receives the acknowledgement and then the resultType: "complete" result. Streams that honor at least one type are unchanged. …