What the MCP TypeScript and Python SDKs Ask of Server Authors - One Server per Request, Token Audience Checks That Are Off by Default, and Tool Input Limits
First Published:
Last Updated:
@modelcontextprotocol/server version 2.3.0 state that an app that uses one server for every request fails on the second request after the upgrade.An app that uses one server object, or one stateless transport, for every HTTP request fails on the second request after this upgrade.
The same release notes also describe a new option,
expectedResource, for comparing a token's audience. However, it notes that this option has no effect unless explicitly configured.When it is not set, nothing changes.
In contrast, the MCP specification (the Authorization page of version 2026-07-28) states that MCP servers MUST validate the audience of tokens. The page of version 2025-11-25 has the same sentence.
MCP servers MUST validate that access tokens were issued specifically for them as the intended audience, according to RFC 8707 Section 2.
The Python SDK (
mcp) version 2.2.0 release notes introduce a corresponding setting, AuthSettings.validate_token_resource, and announce that version 3.0 will make True the default when resource_server_url is set.Set it to `True` or `False`; 3.0 defaults it to `True`.
The two SDKs differ in their versions, feature names, and default settings. Even when sharing the same version number (e.g., 2.3.0), the TypeScript and Python SDKs contain distinct functionalities. Furthermore, changes related to how redirects are handled and limitations on the size of individual Server-Sent Events (SSE) are implemented on the client-side, rather than in the server configuration. While these client-side changes do not directly involve server settings, they alter how the server's responses are received.
This article aims to correlate the changes introduced by both SDKs between September and October of 2026, distinguishing between those that server authors configure and the client-side changes that reach the server, separated by SDK, version, and side. Each entry will detail the default setting, what is returned when the rule is crossed, the item that server authors configure, and the source of the information. The article will present both the audience validation requirements outlined in the specification and the default settings of the SDKs side-by-side. This article is not a summary of the release notes, a migration guide for upgrading to version 2.x, nor a comparison that ranks the two SDKs. This article did not run the SDKs; everything in it comes from checking the sources.
Related articles on this site:
- Migrating to the Stateless Model Context Protocol - What Breaks in Session-Based Servers and What Replaces It
- MCP Server on AWS Lambda Complete Guide - Building Model Context Protocol Servers with Streamable HTTP and OAuth 2.1
- Which MCP Clients a Remote MCP Server Lets In - Client ID Metadata Documents, Pre-Registration, Deprecated Dynamic Client Registration, and the Allowlists Layered on Top
- Network Egress in Claude Managed Agents - allowed_hosts, the Package Manager and MCP Switches, and the Two Rules That Stop web_fetch
- Where the Orchestration Program Runs - Programmatic Tool Calling in the Claude and OpenAI APIs, and Code Mode in Agent Harnesses
Table of Contents
- 1. Introduction — Scope, Verification Date, and Status
- 2. Sides, SDKs, Versions, and How to Read the Tables
- 3. Mapping Versions to Changes
- 4. Reusing One Server Across Requests — TypeScript SDK 2.3.0
- 5. Token Audience — The Specification's MUST and the SDK Defaults
- 6. Layers of Limits — Each Set by the Receiving Side
- 7. Where Client-Side Changes Reach the Server
- 8. All the Rules on One Page
- 9. Where the Sources Disagree and Where No Statement Was Found
- 10. Frequently Asked Questions about the MCP TypeScript SDK and Python SDK
- 11. Summary
- 12. References
1. Introduction — Scope, Verification Date, and Status
This chapter defines the scope of this article, lists the versions released from September to October 2026, outlines the status of the two SDKs, and gives the verification date and the materials consulted.1.1 What This Article Covers and What It Does Not
This article covers the following changes to the MCP TypeScript SDK and Python SDK, occurring between September and October 2026:- The change by which a TypeScript SDK server serves one connection at a time and a transport without sessions serves one request, along with an analysis of configurations that will break and those that will continue to function (Section 4).
- A comparison of the
expectedResourcein the TypeScript SDK and thevalidate_token_resourcein the Python SDK, specifically how they validate token audiences, and their relationship to the specification's MUST requirements (Section 5). - Limits on HTTP body size, the number of input elements in tools, the size of individual SSE events, the number of sessions, and the limits for lifetime, along with an examination of which side (client or server) these limits affect (Section 6).
- Where client-side changes related to redirect handling and limits on SSE events reach the server, and the differences in how the
x-mcp-headeris handled by each SDK (Section 7). - Changes that also went into the 1.x maintenance lines (Section 3).
The MCP server discussed in this article is also a destination of the connections covered in Network Egress in Claude Managed Agents, a companion article published alongside this one. That article states that the MCP connector of Claude Managed Agents connects to the MCP server from Anthropic's servers.
This article does not cover the following.
- The transition from version 1.x to 2.x (including package splitting, migration to ESM only, Node.js versions, Standard Schema, codemod, and the renaming of
FastMCPtoMCPServer), as well as the migration to version 2026-07-28 of the specification. The previously published Migrating to the Stateless Model Context Protocol covers this. - The reasons the specification requires audience validation, and the configuration for integrating OAuth with an MCP server running on AWS Lambda. The previously published MCP Server on AWS Lambda Complete Guide covers this.
- Which MCP clients a remote MCP server will accept. The previously published Which MCP Clients a Remote MCP Server Lets In covers this.
- Layered defenses on the client-side, measures against DNS rebinding, and validation of the
OriginandHostheaders. The previously published MCP Tool Poisoning Defense Guide and the documentation of each SDK cover this. TypeScript SDK 2.3.0 allows entries likemoz-extension://*to be specified in theallowedOriginsfield, but this article does not cover that. - SDKs for C#, Go, Rust, Ruby, and others. This article does not investigate other SDKs.
- An explanation of RFC 8707. In Section 5.1, this article quotes only the one sentence of RFC 8707 Section 2 that the specification cites.
- The process for passing tokens issued for a different server, the process for redirecting credentials to a different origin, and methods for creating inputs that exceed limits. This article only describes where the rules take effect, what is returned when they are exceeded, and what settings the server author needs to configure.
- Which of the two SDKs to use. This article does not rank the two SDKs.
1.2 Versions Covered by This Article
This article covers the following versions, listed in order of their publication dates. Python SDK versions 2.0.0 and 2.1.0 are included solely due to changes related to the maximum size of HTTP request bodies (see Section 6.1). Publication dates are provided in UTC, based on thetime value in the npm registry and the upload_time value in PyPI. The date can differ by one day from the date in Japan.| Package | Version | Published (UTC) | Line |
|---|---|---|---|
mcp (Python) | 2.0.0 | 2026-07-28T13:45Z | 2.x |
mcp (Python) | 2.1.0 | 2026-08-24T19:04Z | 2.x |
mcp (Python) | 1.30.0 | 2026-09-07T14:34Z | 1.x (Maintenance) |
mcp (Python) | 2.2.0 | 2026-09-07T16:06Z | 2.x |
@modelcontextprotocol/server | 2.1.0 | 2026-09-23T15:45Z | 2.x |
@modelcontextprotocol/sdk | 1.32.0 | 2026-10-02T17:32Z | 1.x (Maintenance) |
@modelcontextprotocol/express | 2.0.2 | 2026-10-02T17:44Z | 2.x |
@modelcontextprotocol/client | 2.3.0 | 2026-10-02T17:46Z | 2.x |
@modelcontextprotocol/server | 2.3.0 | 2026-10-02T17:48Z | 2.x |
mcp (Python) | 2.3.0 | 2026-10-02T22:06Z | 2.x |
@modelcontextprotocol/server-legacy | 2.3.1 | 2026-10-05T11:50Z | 2.x |
As of the article's verification date of October 15, 2026, npm's
latest version shows @modelcontextprotocol/server and @modelcontextprotocol/client at version 2.3.1, @modelcontextprotocol/sdk at 1.32.1, and @modelcontextprotocol/express at 2.0.2. The latest version of mcp on PyPI is 2.3.0, and there is no version 2.3.1 available for the Python SDK. The release notes for @modelcontextprotocol/server version 2.3.1 only mention the upgrade of the dependent @modelcontextprotocol/core to version 2.3.1.The TypeScript SDK has different versions for each package. The repository's v2.3.0 release page lists the versions of the packages included in the 2.3.0 release in a table. It shows
@modelcontextprotocol/express and @modelcontextprotocol/hono at version 2.0.2, @modelcontextprotocol/node at 2.1.1, and @modelcontextprotocol/fastify at 2.0.1. When this article refers to "TypeScript SDK 2.3.0," it is referring to versions 2.3.0 of @modelcontextprotocol/server and @modelcontextprotocol/client.1.3 Status
The README file for the main branch of the TypeScript SDK calls v2 the stable release line.This is the `main` branch: v2 of the SDK (`@modelcontextprotocol/server`, `@modelcontextprotocol/client`), the stable release line, implementing the 2026-07-28 MCP spec.
The same README file states that v1.x (
@modelcontextprotocol/sdk) will continue to receive bug fixes and security updates for at least six months after the release of v2. This article does not calculate the end date of that period.continues to receive bug fixes and security updates for at least six months after the v2 release (2026-07-27)
The release notes for version 2.0.0 of the Python SDK state that v1.x is in a maintenance state. Within the same paragraph, two different descriptions are given regarding what v1.x will continue to receive. Section 10.7 of the previously published Migrating to the Stateless Model Context Protocol covers this disagreement. This article only links to it from Section 9.1.
As of this article's verification date, no announcement of retirement or of integration into a successor was found for either SDK. The search covered the release pages listed in Section 1.4 and the README files of both repositories. The SDKs page of the MCP documentation lists both the TypeScript and Python SDKs as Tier 1 SDKs.
1.4 Verification Date and Sources Read
This article was written after reviewing the following materials on October 15, 2026:- Release pages for two SDK repositories. For TypeScript:
@modelcontextprotocol/serverversions 2.1.0 and 2.3.0, 2.3.1;@modelcontextprotocol/clientversion 2.3.0;@modelcontextprotocol/expressversions 2.0.1 and 2.0.2;@modelcontextprotocol/server-legacyversion 2.3.1;@modelcontextprotocol/sdkversions 1.32.0 and 1.32.1, as well as the summary page for versions 2.3.0 and 2.3.1. For Python: versions 1.30.0, 2.0.0, 2.1.0, 2.2.0, and 2.3.0. - Source code on the main branch for both SDKs. For TypeScript: server-side files
bearerAuth.ts,streamableHttp.ts,mcp.ts, andserver.ts, as well as client-side filesstreamableHttp.tsandsse.ts. For Python: filesauth/settings.py,auth/middleware/bearer_auth.py,streamable_http_manager.py, and client-side filestreamable_http.py, among others. The behavior of the 1.x lines was verified by examining the source code for the Bearer token validation in the 1.x branches of both SDKs. - Documentation for the TypeScript SDK (version 2) including pages such as "Require authorization," "Tools," and "Serve over HTTP," as well as documentation for the Python SDK including pages such as "Authorization," "Deploy & scale," "Header parameters," and "Migration Guide: v1 to v2."
- Versions and publication dates on npm and PyPI.
- The MCP specification: the Authorization pages of versions 2026-07-28 and 2025-11-25, the 2026-07-28 version's "Tools" and "Changelog" pages, and the SDKs page of the MCP documentation.
- RFC 8707 (IETF datatracker).
The SDK documentation is updated for each version. The documentation referenced in this article reflects the content available on the main branch as of the verification date.
2. Sides, SDKs, Versions, and How to Read the Tables
This chapter defines the "sides" referred to in this article, and establishes the columns and values presented in the tables. Furthermore, it clarifies distinctions between words with the same spelling but different meanings.2.1 Two Sides and the Meaning of "Reaching the Server"
This article divides changes into two distinct sides:- Server-side (
Server): Changes that take effect in the MCP server. The server author determines these, either through the server's code or configuration. - Client-side (
Client): Changes that take effect in the MCP client. The server author cannot configure these. The person who builds or uses the MCP client determines them.
Within client-side changes, this article focuses solely on those that alter how the client receives responses from the server. For example, if a server endpoint returns a redirect to a different origin, a client on the versions covered in Section 7.1 will not follow that redirect. This rule is enforced in the client and is not a configurable item for the server author. Nevertheless, it can affect whether the client can connect to that server. This article refers to such changes as "reaching the server" changes.
Figure 2 (see Section 6.5) lists which rules are applied on each side.
2.2 Table Columns
The tables in this article use five columns shared by three articles published together. The five columns have the same meaning in the three articles.Enforced Where: The location where the rule is enforced. In other words, who is responsible for enforcing it.Default: Whether the rule is on or off by default, or the default value.When It Is Crossed: What is returned when the rule is crossed.Your Setting: The item that the user can configure. If the source does not list a setting, this article writesNone stated.Stated In: The source document for the information in this row, indicated by the page title and section name.
In addition to these, this article uses three more columns:
Rule: The rule that the row addresses. This column has the same name as the column in Where the Orchestration Program Runs, a companion article published alongside this one.Side: The side on which the rule applies. This column is added in this article, and the values areServerandClient.SDK and Version: The SDK and version in which the rule is implemented. This column is added in this article; for TypeScript SDKs, it uses the package name and version, and for Python SDKs, it usesmcpand the version.
In this article, the user in
Your Setting is the server author for rows on the server side, and the person who builds the MCP client for rows on the client side.This article uses the following values for
Enforced Where:The MCP server (TypeScript SDK): Applies in the MCP server written using the TypeScript SDK.The MCP server (Python SDK): Applies in the MCP server written using the Python SDK.The MCP client (TypeScript SDK): Applies in the MCP client written using the TypeScript SDK.The MCP client (Python SDK): Applies in the MCP client written using the Python SDK.The HTTP adapter (Express): Applies in the@modelcontextprotocol/expressadapter.Your application: Applies in the server author's code, not within an SDK.The source does not say.: The source does not state where the rule applies.
This article uses the following values for
When It Is Crossed:SdkError ALREADY_CONNECTED: Theconnect()function is rejected with theSdkErrorcodeALREADY_CONNECTED.500: An HTTP 500 error is returned.500 with -32603: An HTTP 500 error and a JSON-RPC error-32603are returned.401 invalid_token: An HTTP 401 error and an OAuth error codeinvalid_tokenare returned.413: An HTTP 413 error is returned.400 with -32600: An HTTP 400 error and a JSON-RPC error-32600are returned.503: An HTTP 503 error is returned.404 on the next request: An HTTP 404 error is returned on the next request.isError: true tool result: The tool call returns a tool result withisError: true.Registration fails (InvalidSignature): Tool registration fails with anInvalidSignatureerror.Warning when tools are listed: A warning is issued each time the list of tools is returned.Request fails with an error naming the target: The client's request fails with an error that names the redirect target.The source does not say.: The source does not state what is returned.
The
Default column gives the default value stated in the source. If the source does not state a default, this article writes The source does not say. If the idea of a default does not apply to a rule, this article writes Not applicable. In the Enforced Where and When It Is Crossed columns as well, if the rule in a row does not stop anything, this article writes Not applicable and gives the source's statement in parentheses.2.3 Words That Share the Same Spelling but Refer to Different Things
This article identifies instances where the same or similar terms refer to different entities. To avoid misreading, this article distinguishes them first.- Resource (2 kinds distinguished in this article): (1) The "resource" as defined in RFC 8707. This is a URI representing the intended recipient (audience) of a token. In the TypeScript SDK, this refers to
AuthInfo.resourceandexpectedResource; in the Python SDK, it refers toAccessToken.resourceandresource_server_url. (2) The "resources" within MCP. This represents one of the functionalities exposed by the MCP server. When this article uses the term "resource," it refers to (1).
- Server (2 kinds distinguished in this article): (1) The MCP server. When this article uses the term "server," it refers to this. (2) The
ServerandMcpServerclasses in the TypeScript SDK, and theServerandMCPServerclasses in the Python SDK. When this article refers to classes, it will present the class names in code format.
- Version (3 kinds distinguished in this article): (1) The version of the SDK (e.g., 2.3.0). (2) The version of the specification (e.g.,
2025-11-25,2026-07-28). While the specification version appears in date format, it represents the version name, not the date the specification was released. (3) The version of the adapter (e.g.,@modelcontextprotocol/express2.0.2). The adapter version in the TypeScript SDK progresses independently of the server version.
- Legacy Sessions: Sessions that continue using the
Mcp-Session-Idheader, as defined in specification versions2025-11-25and earlier. Specification version2026-07-28does not include this session type. The Python SDK's Deploy & scale page notes that when connecting with version2026-07-28, it is stateless without any configuration (Section 4.6).
McpServerandMCPServer: The high-level classes in the TypeScript SDK are namedMcpServer, while the high-level classes in the Python SDK are namedMCPServer. In Python SDK version 1.x, this class was namedFastMCP. The previously published MCP Server on AWS Lambda Complete Guide uses the nameFastMCPfor this class.
2.4 When the Source Does Not Say, and When the Sources Disagree
Each cell of a table holds only a statement from the source, or a summary of it. For a cell that the source does not cover, this article writesThe source does not say. Before writing it, this article searches the full text of the source that the row cites, the pages that source links to, and the other release notes, documentation, and source code of the same SDK, using the words of the row's subject.If the source describes a general rule but does not specifically refer to the subject of that row, this article does not write
The source does not say. Instead, it writes the general rule and the fact that the subject is not named.When the sources disagree, this article lists both statements, each with its source, without favoring either. This article always writes a disagreement as
the sources disagree. The disagreements in this article are summarized in Section 9.1. Statements that were looked for and not found are summarized in Section 9.2, with where and how they were looked for. Not finding a statement does not mean that the behavior does not exist.This article distinguishes three kinds of dates. An SDK version is given by its publication date and time (UTC) on npm or PyPI. A documentation page is given by its page title and this article's verification date, October 15, 2026. The specification is given by its version name.
3. Mapping Versions to Changes
This chapter lists the changes discussed in this article, with each row corresponding to a specific SDK version. Detailed descriptions for each row can be found in Sections 4 through 7.3.1 TypeScript SDK
The following table lists the changes to the TypeScript SDK. In theDefault column, Off means that the behavior does not change unless the option is set.| SDK and Version | Side | Change | Default | Section |
|---|---|---|---|---|
@modelcontextprotocol/server 2.1.0 | Server | Adds maxRequestBodySize, an upper limit on the size of Streamable HTTP POST bodies. | 4 MiB | 6.1 |
@modelcontextprotocol/server 2.1.0 | Server | Limits the array size for JSON-RPC batches to 100 items. | 100 items | 6.1 |
@modelcontextprotocol/server 2.3.0 | Server | A Server or McpServer serves one connection at a time, and a transport without sessions serves one request. | Not applicable | 4 |
@modelcontextprotocol/server 2.3.0 | Server | requireBearerAuth and verifyBearerToken take the expectedResource option. | Off | 5.2 |
@modelcontextprotocol/server 2.3.0 | Server | McpServer takes the maxToolInputElements option. | Off | 6.2 |
@modelcontextprotocol/server 2.3.0 | Server | The warning about an invalid x-mcp-header declaration appears each time tools are listed. | Not applicable | 7.3 |
@modelcontextprotocol/express 2.0.2 | Server | Express's requireBearerAuth now passes the expectedResource. | Off | 5.2 |
@modelcontextprotocol/server-legacy 2.3.1 | Server | requireBearerAuth takes the expectedResource option. | Off | 5.2 |
@modelcontextprotocol/client 2.3.0 | Client | Follows redirects only within the same origin. | Same origin only (plus http to https on the same host), keeping the method | 7.1 |
@modelcontextprotocol/sdk 1.32.0 | Server | requireBearerAuth takes the expectedResource option. | Off | 5.2 |
@modelcontextprotocol/sdk 1.32.0 | Server | McpServer takes the maxToolInputElements option. | Off | 6.2 |
@modelcontextprotocol/sdk 1.32.0 | Client | Follows redirects only within the same origin. | Same origin only (plus http to https on the same host), keeping the method | 7.1 |
@modelcontextprotocol/sdk 1.32.0, in the 1.x maintenance line, also received three of these changes: expectedResource, maxToolInputElements, and the redirect rule. The Upgrade notes and the list of changes in the 1.32.0 release notes do not list the change for reusing one server. That change is in the 2.3.0 server release notes.3.2 Python SDK
The following table lists the changes to the Python SDK.| SDK and Version | Side | Change | Default | Section |
|---|---|---|---|---|
mcp 2.0.0 | Server | Adds an upper limit on the size of Streamable HTTP POST bodies. | 4 MiB | 6.1 |
mcp 2.1.0 | Server | Extends the upper limit on body size to include SSE transport and OAuth endpoints. | 4 MiB | 6.1 |
mcp 2.2.0 | Server | Introduces AuthSettings.validate_token_resource. | Unset (with resource_server_url set, it warns and behaves as False) | 5.3 |
mcp 2.2.0 | Server | Closes stateful sessions after 30 minutes of inactivity. | 30 minutes | 6.4 |
mcp 2.2.0 | Server | Allows up to 10,000 concurrent sessions. | 10,000 | 6.4 |
mcp 2.2.0 | Client | Only follows redirects within the same scheme, host, and port, or from http to https on the same host. | Same origin only (plus http to https on the same host) | 7.1 |
mcp 2.3.0 | Server | Tools with incorrect annotations for x-mcp-header will fail during registration. | Not applicable | 7.3 |
mcp 2.3.0 | Client | Introduces max_sse_event_size (upper limit on the size of a single SSE event). | 1 MiB | 6.3 |
mcp 2.3.0 | Client | If a tool is rejected with HeaderMismatch (-32020), the tool will be re-enumerated and the call will be retried once. | Not applicable | 7.3 |
mcp 1.30.0 | Server | Introduces AuthSettings.validate_token_resource. | Unset (with resource_server_url set, it warns and keeps the earlier behavior) | 5.3 |
mcp 1.30.0 | Server | Closes stateful sessions after 30 minutes of inactivity, and allows up to 10,000 concurrent sessions. | 30 minutes, 10,000 | 6.4 |
mcp 1.30.0 | Client | Only follows redirects within the same scheme, host, and port, or from http to https on the same host. | Same origin only (plus http to https on the same host) | 7.1 |
No feature with the same name as the TypeScript SDK 2.3.0 change for reusing one server,
expectedResource, or maxToolInputElements was found in the Python SDK release notes (2.0.0 to 2.3.0) (see Section 9.2). On the other hand, Python SDK 2.2.0 changed two server-side defaults for legacy sessions (see Section 6.4). Server-side changes are not limited to the TypeScript SDK.4. Reusing One Server Across Requests — TypeScript SDK 2.3.0
This chapter outlines which configurations are affected and which remain unaffected by the server changes in TypeScript SDK 2.3.0. The information presented in this chapter is based on the release notes for@modelcontextprotocol/server 2.3.0 and the v2.3.0 release page in the repository.4.1 The Rule That Changed
The release notes for@modelcontextprotocol/server version 2.3.0 state that a server now serves one connection at a time and that a transport without sessions serves one request.A `Server` or `McpServer` now serves one connection at a time, and a Streamable HTTP server transport without sessions (`sessionIdGenerator: undefined`) serves one request.
The Upgrade notes on the repository's v2.3.0 release page call this change
One server per request. and say that the server and transport should now be created in the request handler. The same section notes that creating a server has been cheap since #2889.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.
What became required here is not creating a server for every request as such. What breaks with version 2.3.0 is a configuration that reuses one server, or one transport without sessions, across all HTTP requests. A configuration that creates one server per session remains unchanged (see Section 4.3).
4.2 Configurations That Break, and What Is Returned
The following table lists four configurations that are subject to failure, as outlined in the 2.3.0 release notes.| Configuration | What Fails | When It Is Crossed | Change |
|---|---|---|---|
Build one server, then build a new transport without sessions for each request and call connect(). | Second request and all subsequent requests. | SdkError ALREADY_CONNECTED | Move new McpServer(...) and its registrations into the handler. |
| Build one transport without sessions and use it for every request. | Second request. | WebStandardStreamableHTTPServerTransport.handleRequest() rejects; NodeStreamableHTTPServerTransport.handleRequest() returns 500. | Create and connect the server and transport in the handler. |
Pass createMcpHandler(() => server) a function that returns a server built only once. | Requests arriving while another request is being processed. | 500 with -32603 | Pass a function that creates the server, such as createMcpHandler(buildServer). |
| Use one server for every session. | Second session's initialize call. | SdkError ALREADY_CONNECTED | Create a server for each session. |
Regarding the first configuration, the release notes specify that if the handler closes the transport at the end of the response, requests that arrive one after another keep working, and a request that overlaps another one fails. Similarly, in the third configuration, a request that arrives after the previous response has been read to its end still works. In both cases, failures are not apparent as long as requests do not overlap.
If the handler closes the transport when the response ends, requests that arrive one after the other still work and a request that overlaps another one fails.
In the second configuration, when
WebStandardStreamableHTTPServerTransport.handleRequest() rejects, the message provided in the release notes is as follows:Stateless transport cannot be reused across requests. Create a new transport per request.
In the third configuration, when a
500 error is returned, the reason for the error is only available through the onerror option.the reason is reported only through the `onerror` option.
4.3 Configurations That Do Not Change
The same release notes list five things that keep 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`.
createMcpHandler(buildServer) does not change as long as the function it receives always returns a new server. While createMcpHandler(() => server) may appear to be the same call to createMcpHandler, it only returns a single, pre-existing server, making it equivalent to the third configuration described in Section 4.2. The only difference between the two is whether the passed function creates a new server or returns an already-created one.Figure 1 illustrates the difference between a configuration that shares a single server and one that creates a new server for each request.

4.4 What the Caller Sees
What the calling side sees whenconnect() or handleRequest() rejects depends on the host where the server runs. The release notes state the following:What the caller sees when `connect()` or `handleRequest()` rejects depends on the host. Express 5, Fastify and Hono answer `500`. A plain `node:http` listener without its own error handling gets an unhandled rejection, which ends the process.
When using the raw
node:http and a listener without custom error handling, a rejection in the configuration described in Section 4.2 will cause the process to terminate. In the same release, the examples in the README files for @modelcontextprotocol/express, @modelcontextprotocol/fastify, @modelcontextprotocol/hono, and @modelcontextprotocol/node, as well as the JSDoc examples for the two transports, have been rewritten to create a server and transport for each request.4.5 The Form on Per-Request Runtimes
The Serve over HTTP page in the TypeScript SDK documentation provides an example where thecreateMcpHandler function receives a function that creates and returns a new McpServer instance. The following code is an example from that page. The process of creating the server and registering tools is contained in the function passed to createMcpHandler.import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';
const handler = createMcpHandler(() => {
const server = new McpServer({ name: 'notes', version: '1.0.0' });
server.registerTool(
'add-note',
{
description: 'Save a note',
inputSchema: z.object({ text: z.string() })
},
async ({ text }) => ({ content: [{ type: 'text', text: `Saved: ${text}` }] })
);
return server;
});
The same page states that this function runs once per HTTP request, and says to put tool, resource, and prompt registrations inside the function, not on a shared instance outside it.
The factory runs once per HTTP request: a fresh instance serves every request, and the handler holds nothing between requests. Register tools, resources, and prompts inside the factory, never on a shared instance outside it.
The same page notes that on web-standard runtimes such as Cloudflare Workers, Deno, and Bun,
export default handler alone mounts the handler. In Node.js frameworks, the handler is wrapped once with toNodeHandler from @modelcontextprotocol/node.The previously published MCP Server on AWS Lambda Complete Guide covers the configuration for running an MCP server on AWS Lambda. Section 9.6 of the previously published Migrating to the Stateless Model Context Protocol states that when implementing on Lambda, users should verify the SDK used and the supported status of AWS Labs adapters by referring to their respective original documentation. This article does not verify how the Lambda adapter handles the changes in TypeScript SDK version 2.3.0.
4.6 For the Python SDK
No change that prohibits reusing a singleMCPServer instance was found in the release notes for the Python SDK (versions 2.0.0 through 2.3.0) (see Section 9.2). The Deploy & scale page in the Python SDK documentation states that a connection on version 2026-07-28 is already stateless, with nothing to configure.on 2026-07-28 you are already stateless, with nothing to configure.
That same page also indicates that the
stateless_http setting only applies to the legacy specification.stateless_http is a knob for the legacy leg only, and the modern path is sessionless by construction.
Python SDK version 2.2.0 introduced two default changes regarding stateful sessions for the legacy specification. These changes are to close sessions after 30 minutes of inactivity and to limit the number of concurrently open sessions to 10,000 (see Section 6.4). Connections on version 2026-07-28 and stateless servers are not affected by these changes.
5. Token Audience — The Specification's MUST and the SDK Defaults
This chapter outlines the token audience validation process, detailing what the specification requires and what defaults are implemented in the two SDKs. The reasons behind the specification's requirement for this validation, and the configuration for integrating OAuth on AWS Lambda, are discussed in Section 11.3 of the previously published MCP Server on AWS Lambda Complete Guide.5.1 What the Specification Requires
The Authorization page of the MCP specification, in both version 2026-07-28 and version 2025-11-25, contains the following statement in its Token Handling section.MCP servers MUST validate that access tokens were issued specifically for them as the intended audience, according to RFC 8707 Section 2.
This MUST is a requirement on the MCP server. The same section also states that in cases of validation failure, the server must return an HTTP 401 error for invalid tokens and expired tokens.
Invalid or expired tokens MUST receive a HTTP 401 response.
Section 2 of RFC 8707, referenced by the specifications, states (SHOULD) that the authorization server should limit the audience of the access tokens it issues to the resource indicated by the
resource parameter.The authorization server SHOULD audience-restrict issued access tokens to the resource(s) indicated by the resource parameter.
While the SHOULD in RFC 8707 applies to the authorization server, the MUST in the specification is a requirement on the MCP server. The SDK settings in the next two sections are what can check the audience on the MCP server side once they are set.
5.2 TypeScript SDK's expectedResource
@modelcontextprotocol/server version 2.3.0 has added the expectedResource option to requireBearerAuth and verifyBearerToken. The release notes describe the behavior when the option is configured versus when it is not, as follows: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.
Based on this description, the server author has two decisions to make:
- What to set
expectedResourceto: The release notes indicate that this value is what the authorization server includes in the token for this server, and typically this is the server's URL. The type of this value isURL. - Whether the token validation function populates
AuthInfo.resource: The SDK compares the value that the validation function returns inAuthInfo.resourcewithexpectedResource. The release notes suggest populating this from, for example, theaudclaim. If the validation function does not populateAuthInfo.resource, every token is answered with 401 whenexpectedResourceis set.
The JSDoc for the source code states that when the option is not set,
AuthInfo.resource is not compared with anything:When unset, `AuthInfo.resource` is not compared with anything.
The "Require authorization" page in the TypeScript SDK documentation provides an example of
requireBearerAuth configured with expectedResource. The following code snippet represents the first line of an example using a web standard host. verifier is an object containing the function that validates the token, and mcpServerUrl is a URL representing the URL of this server.const gate = requireBearerAuth({ verifier, requiredScopes: ['mcp'], expectedResource: mcpServerUrl });
When using Express,
@modelcontextprotocol/express also has to be upgraded. The release notes for @modelcontextprotocol/express version 2.0.2 state that version 2.0.1 does not pass this option.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.
The next sentence says that because this item is missing from the type definition for the option in version 2.0.1, specifying
expectedResource will result in a type error in TypeScript. The table on the v2.3.0 release page of the repository indicates that in the v2.3.0 release, @modelcontextprotocol/express has been updated to version 2.0.2.expectedResource is also included in two other packages.@modelcontextprotocol/sdk1.32.0 (1.x maintenance line): The Upgrade notes listexpectedResourceonrequireBearerAuthas a new option that is off unless you set it.@modelcontextprotocol/server-legacy2.3.1: The release notes state that the option was added to this package'srequireBearerAuthso that it matches the 1.x middleware it is a copy of. This package is otherwise frozen.
No announcement that the TypeScript SDK will turn
expectedResource on by default in the future was found (see Section 9.2).5.3 Python SDK's validate_token_resource
The Python SDK version 2.2.0 added validate_token_resource to the AuthSettings. The "New" section of the release notes states:`AuthSettings.validate_token_resource`: only accept tokens your `TokenVerifier` reports as issued for this server (#3447).
The default differs from that of
expectedResource in the TypeScript SDK. The Authorization page in the Python SDK's documentation notes that when resource_server_url is configured but validate_token_resource is not, a warning is issued, and it behaves as if set to False.Leaving it unset while `resource_server_url` is set warns (`MCPDeprecationWarning`) and behaves as `False`; 3.0 makes `True` the default for resource servers.
The release notes for version 2.2.0 list this warning as one of two new
MCPDeprecationWarning messages, and say to set it to True or False. In 2.x, the behavior stays the same as before for both warnings.Both keep working as before in 2.x; this mostly matters if your tests turn warnings into errors.
Three more points about the Python SDK's behavior come from its source code:
- When
validate_token_resource=True,resource_server_urlis required: The source code forAuthSettingsindicates that ifTrueis set without a configuredresource_server_url, aValueErrorwill be raised. - Comparison Method: The code that verifies the Bearer token compares
AccessToken.resourceandresource_server_urlas URLs, ignoring trailing slashes. The source code comments state that when comparing as URLs, differences in case and in how the default port is written do not matter. In contrast, the TypeScript SDK'sexpectedResourceperforms a string comparison (see Section 5.2). - Return Value: If the
resourcedoes not match, the token will not be authenticated, and the part that requires authentication returns 401 withinvalid_token.
The Python SDK version 1.30.0 (part of the 1.x maintenance line) also added the same
AuthSettings.validate_token_resource setting. The release notes for version 1.30.0 state that in version 1.x, even when a warning is issued, it continues to function as before.That the default becomes
True in 3.0 is an announcement in the 2.2.0 release notes and the documentation. This article does not state when 3.0 will be released.5.4 Checking the Audience in the Validation Function Instead of an SDK Setting
The specification's MUST does not require using an SDK setting. The Authorization page of the Python SDK documentation describes the cases with and withoutvalidate_token_resource.Turn it on when your authorization server binds tokens to the `resource` the client requested, which MCP clients always send.
Leave it off when your authorization server uses its own audience identifiers (an Auth0 API identifier, an Entra application ID) and check `aud` in your verifier instead, returning `None` for a token that isn't for this server.
The "Require authorization" page of the TypeScript SDK documentation provides an example where, in the function that validates the token, the entry of the
aud claim on this server's origin is found and placed into AuthInfo.resource. The aud claim may contain a single value, a list of values, or may be absent altogether. The page says to report this server's entry in those cases, and to leave resource unset when there is none.In either SDK, the server author decides whether to check the audience through the SDK setting or in the token validation function, based on the tokens issued by the authorization server. Section 11.3 of the previously published MCP Server on AWS Lambda Complete Guide provides an example of a Python function that checks the
aud claim, as well as details on Amazon Cognito configuration. Section 6 of the previously published MCP Server Testing and Debugging Guide covers testing whether a server rejects tokens issued for another server.5.5 The Specification and the Two SDKs Side by Side
The following table outlines the specifications and descriptions for two SDKs regarding audience validation.| Source | Requirement or Setting | Default | When It Is Crossed | Stated In |
|---|---|---|---|---|
| MCP Specifications (2025-11-25, 2026-07-28) | The MCP server must verify that a token has been issued for itself (MUST). | Not applicable | Invalid tokens result in a 401 (MUST). | Authorization, Token Handling |
| RFC 8707 | The authorization server should limit the token's audience to the resource (SHOULD). | Not applicable | The source does not say. | Section 2 |
@modelcontextprotocol/server 2.3.0 | expectedResource | Off (When it is not set, nothing changes.) | 401 invalid_token | Release notes, bearerAuth.ts |
@modelcontextprotocol/sdk 1.32.0 | expectedResource | Off | 401 invalid_token | Release notes, bearerAuth.ts (v1.x) |
mcp 2.2.0 | validate_token_resource | Unset (with resource_server_url set, it warns and behaves as False); True announced for 3.0 | 401 invalid_token | Release notes, Authorization, bearer_auth.py |
mcp 1.30.0 | validate_token_resource | Unset (with resource_server_url set, it warns and keeps the earlier behavior) | 401 invalid_token | Release notes, bearer_auth.py (v1.x) |
The specification's MUST and the SDKs' default of off are not a case where the sources disagree. The MUST is a requirement on the server, and the SDKs added one way to meet it, off by default. A server that does not use the SDK setting can still meet the MUST by checking the audience in its validation function (see Section 5.4). Conversely, upgrading the SDK alone does not check the audience.
6. Layers of Limits — Each Set by the Receiving Side
This chapter differentiates the upper limits of the two SDKs based on which side they apply to and what they measure. The upper limits are determined by the receiving party. The HTTP body and tool input are received by the server, while SSE events are received by the client.6.1 HTTP Body Size
TypeScript SDK:@modelcontextprotocol/server version 2.1.0 (September 23, 2026) limits the size of the body of Streamable HTTP requests to 4 MiB by default. The release notes for version 2.1.0 state that requests with a body exceeding this limit will receive a 413 Payload Too Large error before any parsing occurs. This limit can be adjusted using the maxRequestBodySize option. The source JSDoc documentation describes the default value and how the SDK handles a body that has already been parsed and passed as parsedBody as follows.A body over the bound (declared `Content-Length`, or observed while streaming) is answered `413` before anything is parsed. Not applied when the caller supplies `parsedBody`. Must be a positive number.
@default 4194304 (4 MiB)
This limit only applies when the transport itself reads the body. The same release notes indicate that hosts that parse the body and pass it as
parsedBody skip the SDK's reading and its associated limit. The release notes also mention that both the Express adapter and stdio have their own limits on reading. For the Node.js adapter's toNodeHandler and toWebRequest, the release notes say that the adapter's limit applies before the handler's, so both have to be raised. A change in version 2.1.0 also limits JSON-RPC batch arrays to 100 items. Batches exceeding this length will receive a 400 and -32600 error, and will not be processed.Python SDK: The Python SDK version 2.0.0 also has a 4 MiB limit on the body of Streamable HTTP POST requests. The Python SDK's documentation, specifically the "Migration Guide: v1 to v2" page, states the following:
V2 applies a 4 MiB default limit to Streamable HTTP POST bodies and returns HTTP 413 before parsing the JSON or creating a session when that limit is exceeded.
This limit can be modified using the
max_request_body_size option within either run() or streamable_http_app(). The Python SDK version 2.1.0 extends this limit to the SSE transport and the OAuth endpoints.The 4 MiB limit is not exclusive to the TypeScript SDK. Both SDKs, by default, impose a 4 MiB limit on the size of the body received by the server.
6.2 Number of Input Elements for Tools
In the TypeScript SDK,McpServer in @modelcontextprotocol/server 2.3.0 takes the maxToolInputElements option. The release notes state:It is off by default, so behavior is unchanged unless you set it. When it is set and a call exceeds it, that call is answered with an `isError: true` tool result that names the limit, before the input schema runs, and the server keeps serving.
This option counts the combined number of array elements and object members in the
arguments of a single tools/call. The value must be a number greater than or equal to 1, or Infinity (indicating no limit). Any other value will be rejected when the server is created. The release notes say to set this value above the largest arguments that the tools legitimately accept, while also noting that maxRequestBodySize remains the primary limit for request size. The Tools page in the TypeScript SDK's documentation provides the following example.const server = new McpServer({ name: 'my-server', version: '1.0.0' }, { maxToolInputElements: 10_000 });
@modelcontextprotocol/sdk version 1.32.0 also lists maxToolInputElements on McpServer as a new option that is off unless you set it. No setting in the Python SDK that counts the same thing was found (see Section 9.2).6.3 Size of a Single SSE Event
Python SDK 2.3.0 added themax_sse_event_size option to the MCP client's streamable_http_client and StreamableHttpParameters. The release notes state:The default stays 1 MiB per SSE event; raise it, or pass `None`, for larger tool results (#3600).
This option defines the maximum size of a single SSE event received by the client; it does not represent the maximum size of the server's response. It concerns whether the Python SDK 2.3.0 client, with its default settings, will accept tool results exceeding 1 MiB in a single SSE event from the server using Streamable HTTP. The release notes do not specify what happens on the client-side when this limit is exceeded. This option requires
httpx2 version 2.10.0 or later.The "Client transports" page of the Python SDK documentation states the following about exceeding the limit:
An oversized event in a POST response or resumed stream fails that request with an SSE error. On the background GET stream, the client logs the error and retries the stream.
The same size limit setting was not found in the TypeScript SDK client (see Section 9.2). The release notes for
@modelcontextprotocol/client 2.3.0 mention that receiving a large message as a single SSE event is now faster, but do not specify a size limit.6.4 Session Count and Lifetime — Legacy Sessions in the Python SDK
The Python SDK version 2.2.0 imposed two default limits on stateful sessions of the legacy specification (version 2025-11-25 and earlier). The release notes state:A stateful session with nothing in flight for 30 minutes is closed. The client's next request gets a 404 and it has to initialize again.
A server also holds at most 10 000 sessions at once; beyond that, new sessions get a 503.
The same release notes also state that clients that leave GET streams open, along with stateless servers, and connections on version 2026-07-28 are not affected by this change. Both limits can be turned off by setting
session_idle_timeout=None and max_sessions=None. The Python SDK version 1.30.0 also included the same two limits, using the identically named settings within FastMCP.6.5 The Layers of Limits Side by Side
The following table lists the upper limits defined in Sections 6.1 through 6.4.| Limit | Side | SDK and Version | Default | When It Is Crossed | Your Setting |
|---|---|---|---|---|---|
| HTTP Request Body Size | Server | @modelcontextprotocol/server 2.1.0 | 4 MiB (Does not apply when passing parsedBody) | 413 | maxRequestBodySize |
| Number of Items in a JSON-RPC Batch | Server | @modelcontextprotocol/server 2.1.0 | 100 | 400 with -32600 | None stated |
| HTTP Request Body Size | Server | mcp 2.0.0 (also applies to SSE and OAuth in 2.1.0) | 4 MiB | 413 | max_request_body_size |
| Number of Input Elements for Tools | Server | @modelcontextprotocol/server 2.3.0, @modelcontextprotocol/sdk 1.32.0 | Off | isError: true tool result | maxToolInputElements |
| Legacy Session Inactivity | Server | mcp 2.2.0, 1.30.0 | 30 minutes | 404 on the next request | session_idle_timeout |
| Number of Legacy Sessions | Server | mcp 2.2.0, 1.30.0 | 10,000 | 503 | max_sessions |
| Size of a Single SSE Event | Client | mcp 2.3.0 | 1 MiB | Request fails with an SSE error (the background GET stream logs it and retries) | max_sse_event_size |
Figure 2 lists the upper limits and audience settings, as well as redirection rules, for both sides. Figure 2 only displays the value of 1 MiB; other values are listed in this table.

7. Where Client-Side Changes Reach the Server
This chapter lists changes made on the MCP client that affect how the client receives responses from the server. None of these are settings that the server author configures in the SDK. Section 7.3 also covers when each SDK's server reports an invalidx-mcp-header declaration.7.1 Redirects Only Within the Same Origin
The release notes for@modelcontextprotocol/client version 2.3.0 state that the HTTP client transport and OAuth client helper now only follow redirects within the same origin.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.
The release notes for the Python SDK version 2.2.0 also state that
Client, streamable_http_client, and sse_client only follow redirects within the same scheme, host, and port, or from http to https on the same host. In other redirect scenarios, the call will fail with an MCPError, but the session remains valid. The Python SDK does not apply the follow_redirects setting passed to the provided httpx2.AsyncClient to MCP requests. The same rule applies to @modelcontextprotocol/sdk version 1.32.0 and the Python SDK version 1.30.0. In 1.30.0, a redirect elsewhere fails the request with httpx.HTTPStatusError.This rule is enforced on the client-side. What reaches the server author is the following case. If the MCP endpoint returns a redirect to a different host or port, the client in both SDKs will not follow the redirect, and the request will fail. The release notes of both SDKs say to use the URL that the redirect points to as the endpoint URL; the Python release notes add the condition that it is the server you meant.
If your endpoint redirects to another origin, configure the transport with the URL it redirects to.
If that other URL is the server you meant, use it as the endpoint URL.
In the TypeScript SDK, setting
redirectPolicy: 'follow' on the transport allows the client to delegate the handling of redirects to the underlying fetch implementation. The release notes indicate that this behavior remains unchanged from previous versions. Within a browser environment, without this setting, redirected requests will fail. It is the responsibility of the developer creating the MCP client to determine this setting.7.2 The SSE Event Limit Reaches Large Tool Results
Themax_sse_event_size setting in Section 6.3, found in the Python SDK client configuration, determines whether the client will receive tool results returned by the server in a single SSE event that exceed 1 MiB. According to the release notes for Python SDK version 2.3.0, for larger tool results, this limit should be raised or set to None. This setting is configured by the client developer.On the server side,
maxRequestBodySize and max_request_body_size define the maximum size of the request body the server will accept. These run in the opposite direction from max_sse_event_size; increasing max_sse_event_size does not affect the maximum size of the request body the server can receive.7.3 Invalid x-mcp-header Declarations
The specification, version 2026-07-28, defines the annotation x-mcp-header to map tool argument values to HTTP headers in the format Mcp-Param-{Name}. The specification's Changelog page refers to this change as SEP-2243. The Tools section of the specification states that Streamable HTTP clients MUST reject the definition of tools with an invalid x-mcp-header.Clients using the Streamable HTTP transport MUST reject tool definitions where any x-mcp-header value violates these constraints.
The same page clarifies that "rejecting" means excluding the tool from the results of
tools/list. This rule is a requirement on clients, meaning tools with incorrect declarations will be removed from the client's list. The two SDKs handle this error differently on the server side.- Python SDK 2.3.0:
@mcp.tool(),add_tool, andTool.from_functionthrow anInvalidSignatureerror when registering tools with an incorrectx-mcp-headerannotation. The release notes state that previously, the server would start, and clients using the 2026-07-28 version would silently remove the tool from their list. - TypeScript SDK 2.3.0: Warnings about incorrect
x-mcp-headerdeclarations are not issued when the tool is registered, but rather each time the tool is listed.
Until now the server started, and 2026-07-28 clients silently dropped the tool from their listing.
The warning about an invalid `x-mcp-header` declaration now appears each time tools are listed, not when the tool is registered.
The Python SDK's documentation, on the "Header parameters" page, states that
MCPServer throws an InvalidSignature error, while the lower-level Server performs no validation. The TypeScript SDK's documentation states that tools with an x-mcp-header attached to an argument of type number will no longer appear in Client.listTools() (excluding stdio) when connecting using the 2026-07-28 version. Furthermore, if called by name, the server will reject the request with a 400 error and a -32020 code (HeaderMismatch).On the client side, the Python SDK 2.3.0's
Client.call_tool will re-list the tools and retry the call once after receiving a rejection with a HeaderMismatch (-32020).This difference in handling is not a case where the sources disagree. The specification requires clients to reject, and the two SDKs independently determine when to report this error on the server side.
8. All the Rules on One Page
This chapter consolidates the rules from Sections 4 through 7, presenting them in the shared columns. The table is divided into two sections: one for the server-side and one for the client-side.8.1 The Server Side
| Rule | Side | SDK and Version | Enforced Where | Default | When It Is Crossed | Your Setting | Stated In |
|---|---|---|---|---|---|---|---|
| A single server handles one connection | Server | @modelcontextprotocol/server 2.3.0 | The MCP server (TypeScript SDK) | Not applicable | SdkError ALREADY_CONNECTED | Create a server and transport for each request or session. | Release notes |
| A transport without a session handles one request | Server | @modelcontextprotocol/server 2.3.0 | The MCP server (TypeScript SDK) | Not applicable | 500 (Node transport) | Create a transport for each request. | Release notes |
Pass a pre-built server to createMcpHandler | Server | @modelcontextprotocol/server 2.3.0 | The MCP server (TypeScript SDK) | Not applicable | 500 with -32603 (overlapping requests) | createMcpHandler(buildServer) | Release notes |
| Token audience | Server | @modelcontextprotocol/server 2.3.0, @modelcontextprotocol/sdk 1.32.0, @modelcontextprotocol/server-legacy 2.3.1 | The MCP server (TypeScript SDK) | Off | 401 invalid_token | expectedResource, and a validation function that fills AuthInfo.resource | Release notes, Require authorization |
Pass expectedResource in Express | Server | @modelcontextprotocol/express 2.0.2 | The HTTP adapter (Express) | Not applicable (not passed in 2.0.1) | Not applicable (2.0.1 compares nothing; TypeScript reports expectedResource as a type error) | Upgrade the adapter to 2.0.2. | Release notes |
| Token audience | Server | mcp 2.2.0, 1.30.0 | The MCP server (Python SDK) | Unset (warns if resource_server_url is set) | 401 invalid_token | validate_token_resource, resource_server_url | Release notes, Authorization |
| HTTP request body size | Server | @modelcontextprotocol/server 2.1.0 | The MCP server (TypeScript SDK) | 4 MiB | 413 | maxRequestBodySize | Release notes, streamableHttp.ts |
| HTTP request body size | Server | mcp 2.0.0 (also SSE and OAuth in 2.1.0) | The MCP server (Python SDK) | 4 MiB | 413 | max_request_body_size | Migration Guide: v1 to v2 |
| Number of items in a JSON-RPC batch | Server | @modelcontextprotocol/server 2.1.0 | The MCP server (TypeScript SDK) | 100 | 400 with -32600 | None stated | Release notes |
| Number of input elements for tools | Server | @modelcontextprotocol/server 2.3.0, @modelcontextprotocol/sdk 1.32.0 | The MCP server (TypeScript SDK) | Off | isError: true tool result | maxToolInputElements | Release notes, Tools (TypeScript SDK) |
| Legacy session inactivity and count | Server | mcp 2.2.0, 1.30.0 | The MCP server (Python SDK) | 30 minutes, 10,000 | 404 on the next request, 503 | session_idle_timeout, max_sessions | Release notes |
Incorrect annotation for x-mcp-header | Server | mcp 2.3.0 | The MCP server (Python SDK) | Not applicable | Registration fails (InvalidSignature) | Correct the annotation. | Release notes, Header parameters |
Incorrect declaration for x-mcp-header | Server | @modelcontextprotocol/server 2.3.0 | The MCP server (TypeScript SDK) | Not applicable | Warning when tools are listed | Correct the declaration. | Release notes |
8.2 The Client Side
| Rule | Side | SDK and Version | Enforced Where | Default | When It Is Crossed | Your Setting | Stated In |
|---|---|---|---|---|---|---|---|
| Redirects followed only within the same origin | Client | @modelcontextprotocol/client 2.3.0, @modelcontextprotocol/sdk 1.32.0 | The MCP client (TypeScript SDK) | Same origin only (plus http to https on the same host), keeping the method | Request fails with an error naming the target | redirectPolicy: 'follow' | Release notes |
| Redirects followed only within the same origin | Client | mcp 2.2.0, 1.30.0 | The MCP client (Python SDK) | Same origin only (plus http to https on the same host) | MCPError (SSE connections return httpx2.HTTPStatusError); httpx.HTTPStatusError in 1.30.0 | None stated (modify the endpoint URL) | Release notes |
| Maximum size of a single SSE event | Client | mcp 2.3.0 | The MCP client (Python SDK) | 1 MiB | Request fails with an SSE error (the background GET stream logs it and retries) | max_sse_event_size | Release notes, Client transports |
Tools that violate the x-mcp-header constraint | Client | Specification 2026-07-28 | The MCP client (TypeScript SDK), The MCP client (Python SDK) | Not applicable | Exclude from the results of tools/list (MUST) | None stated | Tools (specification), TypeScript SDK documentation, client/session.py (Python) |
Retrying after a HeaderMismatch error | Client | mcp 2.3.0 | The MCP client (Python SDK) | Not applicable (retry once only) | Not applicable | None stated | Release notes |
9. Where the Sources Disagree and Where No Statement Was Found
This chapter lists where the sources disagree and where no statement was found.9.1 Where the Sources Disagree, and Where They Do Not
Within the scope of this article, the sources disagree in one place:- What Python's SDK v1.x Receives: The release notes for v2.0.0 state, within the same paragraph, that v1.x will only receive security fixes, while also stating that it continues to receive critical bug fixes and security patches. The sources disagree. Section 10.7 of the previously published Migrating to the Stateless Model Context Protocol covers this disagreement.
The following three look like disagreements but are not:
- The specification's MUST and the SDK default of off: The MUST is a requirement on the server, and the SDK setting is one way to meet it (Section 5.5).
- Versions of the Express adapter: The release notes for
@modelcontextprotocol/server2.3.0 state that 2.0.1 does not pass the option on, while npm's@modelcontextprotocol/express'slatestversion is 2.0.2. The table on the v2.3.0 release page indicates that the Express adapter was updated to version 2.0.2 in that release, and the release notes for 2.0.2 contain a sentence saying to upgrade to this release (Section 5.2). - Handling of the
x-mcp-headerand how audiences are compared: The two SDKs differ in when they report incorrect declarations (Section 7.3) and how they compareresourcevalues (Section 5.3). Both SDKs' documentation describes their respective behavior, and there is no direct contradiction between them.
9.2 Where No Statement Was Found
The following table lists statements that were looked for on October 15, 2026, and not found, with where and how they were looked for. Not finding a statement does not mean that the behavior does not exist.| What Was Looked For | Where and How It Was Looked For | Result |
|---|---|---|
Announcement that a future release of the TypeScript SDK will turn on expectedResource by default | Searched the release pages for @modelcontextprotocol/server 2.3.0, 2.3.1, @modelcontextprotocol/server-legacy 2.3.1, @modelcontextprotocol/sdk 1.32.0, 1.32.1, as well as bearerAuth.ts, and the full documentation (v2), using the terms expectedResource, default, future, and will. | No statement was found. |
| Upper limit on the size of a single Server-Sent Events (SSE) event in the TypeScript SDK client. | Searched the client's streamableHttp.ts and sse.ts files, the release pages for @modelcontextprotocol/client 2.3.0, and the full documentation (v2), using the terms maxEventSize, event size, and MiB. | No statement was found. |
| Upper limit on the number of elements in the input for tools in the Python SDK. | Searched the main branch of the Python SDK's MCPServer, tools, low-level Server source code, and five pages of documentation, using the terms max_tool_input, input elements, and elements. | No statement was found. |
Changes prohibiting the reuse of a single MCPServer instance across all requests in the Python SDK. | Searched the release pages for the Python SDK from v2.0.0 to v2.3.0, the files streamable_http_manager.py and low-level Server source code, and five pages of documentation, using the terms ALREADY_CONNECTED, already connected, per request, and cannot be reused. | No statement was found. The docstring for StreamableHTTPSessionManager states that the instance cannot be reused after its run() context has completed. However, this refers to managing sessions in a single application, and does not prohibit reusing the server. |
What happens when the Python SDK client in version 2.3.0 exceeds max_sse_event_size. | Searched the release pages for version 2.3.0, the client's streamable_http.py file, and the Migration Guide: v1 to v2 page, using the terms max_sse_event_size, exceed, and larger. | No statement was found in the release notes or the source. The Client transports page of the documentation states it (Section 6.3). |
9.3 What Changes When the Sources Are Updated
The following sections of this article may change when the documentation is updated. When reading this article, re-read the versions of npm and PyPI, as well as the release pages.- Versions of the two SDKs (Section 1.2). Within the two weeks before this article's verification date, the TypeScript SDK released versions 2.3.0 and 2.3.1, while the Python SDK released version 2.3.0.
- The default behavior of
validate_token_resourcein the Python SDK 3.0 (Section 5.3). - The maintenance period for version 1.x of the TypeScript SDK (Section 1.3).
- Versions of the adapter (Section 5.2).
- The next version of the specification after version 2026-07-28.
10. Frequently Asked Questions about the MCP TypeScript SDK and Python SDK
Q1. Will the token's audience be validated if the SDK is upgraded to version 2.3.0?
No, it will not. In the TypeScript SDK, theexpectedResource setting is off by default, and the release notes state, When it is not set, nothing changes. In the Python SDK, if resource_server_url is configured but validate_token_resource is not, a warning is issued, and it behaves as False. The specification states that the MCP server must validate the audience. Whether to use the SDK's configuration or to check the aud claim within a token validation function is up to the server author (Section 5).Q2. Does the Python SDK also require creating a server for each request, starting with version 2.3.0?
No change that prohibits reusing a singleMCPServer instance across all requests was found in the Python SDK's release notes (from version 2.0.0 to 2.3.0). The Python SDK's documentation states that a connection on version 2026-07-28 is already stateless, with nothing to configure. The failure on the second request when one server is reused is a change in the TypeScript SDK's @modelcontextprotocol/server version 2.3.0 (Section 4).Q3. Does the TypeScript SDK version 2.3.0 require creating a server for each request, regardless of the configuration?
No. The issue arises when a single server or a single transport without sessions is reused across all HTTP requests. Configurations that create a new server each time usingcreateMcpHandler(buildServer), or those that create one server and one transport per session, remain unchanged (see Section 4.3).Q4. Will increasing the max_sse_event_size allow the server to return larger responses?
No. max_sse_event_size defines the maximum size of a single SSE event that the Python SDK client can receive. It is not a limit on the server's overall response size, nor is it related to the maximum size of the body the server can accept (maxRequestBodySize or max_request_body_size) (see Sections 6.3 and 7.2).Q5. Do the 1.x lines include these changes?
Some of them do. The@modelcontextprotocol/sdk 1.32.0 (TypeScript SDK) includes expectedResource, maxToolInputElements, and redirect rules. The Python SDK 1.30.0 includes validate_token_resource, redirect rules, and two limits for legacy sessions. The change for reusing one server is not in the Upgrade notes of the 1.32.0 release notes (Section 3).Q6. With Express, if only @modelcontextprotocol/server is upgraded to 2.3.0, does expectedResource take effect?
No, it does not. @modelcontextprotocol/express version 2.0.1 does not pass expectedResource, so nothing is compared. Upgrade @modelcontextprotocol/express to version 2.0.2 as well. Because this item is not included in the type definitions for the options in version 2.0.1, TypeScript will produce a type error (see Section 5.2).Q7. Are incorrectly declared x-mcp-header values handled consistently across both SDKs?
No, they are not. The Python SDK version 2.3.0's MCPServer throws an InvalidSignature error at the time of tool registration. The TypeScript SDK version 2.3.0, on the other hand, issues a warning each time the tools are listed. The specification states that clients using Streamable HTTP must exclude tools that violate the constraints (Section 7.3).11. Summary
- The two SDKs have different versions, feature names, and default settings: While both the TypeScript SDK (version 2.3.0) and the Python SDK (version 2.3.0) share the same version number, their contents are different. There is no version 2.3.1 available for the Python SDK.
- Among the server-side changes this article covers, only setups that reuse one server break in TypeScript SDK 2.3.0: Reusing one server, or one transport without sessions, for all HTTP requests fails on the second request.
createMcpHandler(buildServer)and setups that build per session do not change. - The audience check is off in the SDK defaults: The specification states that the MCP server must validate the audience. In the TypeScript SDK,
expectedResourceis off unless set. In the Python SDK, ifresource_server_urlis set andvalidate_token_resourceis not, it warns and behaves asFalse. For Express, upgrade the adapter to version 2.0.2. - Limits are determined by the receiving side: The 4 MiB limit for the HTTP body is present in both SDKs' servers. The limit on the number of tool input elements is in the TypeScript SDK's server and is off by default. The Python SDK client has a 1 MiB limit for a single SSE event.
- The Python SDK also changed default settings on the server side: Stateful sessions of the legacy specification close after 30 minutes of inactivity, with at most 10,000 at once.
- Client-side changes reach the server: Both SDKs' clients do not follow redirects to different origins, except from
httptohttpson the same host; the TypeScript client also requires the redirect to keep the method. The release notes for the two SDKs say to use the URL the redirect points to as the endpoint URL (the Python notes add: if it is the server you meant). - The timing for notifying about errors related to
x-mcp-headerdiffers: The Python SDK fails during registration, while the TypeScript SDK issues a warning each time the tool is listed. - Some changes also went into the 1.x lines: The TypeScript SDK (version 1.32.0) and the Python SDK (version 1.30.0) both support audience configuration and redirect rules.
12. References
- Release @modelcontextprotocol/server@2.3.0 - modelcontextprotocol/typescript-sdk - GitHub
- Release @modelcontextprotocol/server@2.3.1 - modelcontextprotocol/typescript-sdk - GitHub
- Release @modelcontextprotocol/client@2.3.0 - modelcontextprotocol/typescript-sdk - GitHub
- Release @modelcontextprotocol/express@2.0.2 - modelcontextprotocol/typescript-sdk - GitHub
- Release @modelcontextprotocol/express@2.0.1 - modelcontextprotocol/typescript-sdk - GitHub
- Release @modelcontextprotocol/server@2.1.0 - modelcontextprotocol/typescript-sdk - GitHub
- Release @modelcontextprotocol/server-legacy@2.3.1 - modelcontextprotocol/typescript-sdk - GitHub
- Release 2.3.0 - modelcontextprotocol/typescript-sdk - GitHub
- Release 2.3.1 - modelcontextprotocol/typescript-sdk - GitHub
- Release 1.32.0 - modelcontextprotocol/typescript-sdk - GitHub
- Release 1.32.1 - modelcontextprotocol/typescript-sdk - GitHub
- Release v2.3.0 - modelcontextprotocol/python-sdk - GitHub
- Release v2.2.0 - modelcontextprotocol/python-sdk - GitHub
- Release v2.1.0 - modelcontextprotocol/python-sdk - GitHub
- Release v2.0.0 - modelcontextprotocol/python-sdk - GitHub
- Release v1.30.0 - modelcontextprotocol/python-sdk - GitHub
- Require authorization - MCP TypeScript SDK
- Serve over HTTP - MCP TypeScript SDK
- Tools - MCP TypeScript SDK
- Supporting protocol revision 2026-07-28 - MCP TypeScript SDK
- Authorization - MCP Python SDK
- Deploy & scale - MCP Python SDK
- Header parameters - MCP Python SDK
- Migration Guide: v1 to v2 - MCP Python SDK
- Client transports - MCP Python SDK
- @modelcontextprotocol/server - npm
- mcp - PyPI
- Authorization - Model Context Protocol (2026-07-28)
- Authorization - Model Context Protocol (2025-11-25)
- Tools - Model Context Protocol (2026-07-28)
- Key Changes - Model Context Protocol (2026-07-28)
- SDKs - Model Context Protocol
- RFC 8707: Resource Indicators for OAuth 2.0
- Migrating to the Stateless Model Context Protocol - What Breaks in Session-Based Servers and What Replaces It
- MCP Server on AWS Lambda Complete Guide - Building Model Context Protocol Servers with Streamable HTTP and OAuth 2.1
- Which MCP Clients a Remote MCP Server Lets In - Client ID Metadata Documents, Pre-Registration, Deprecated Dynamic Client Registration, and the Allowlists Layered on Top
- MCP Server Testing and Debugging Guide - Inspector, Integration Tests, Transports, and CI Regression
- MCP Tool Poisoning Defense Guide - Client-Side Defense in Depth for AI Agents
- Model Context Protocol Specification Version Timeline - Version-by-Version Changes and Adoption Milestones
- MCP Server Implementation Reference - Anthropic, OpenAI, Google, Cloudflare, and AWS
- Network Egress in Claude Managed Agents - allowed_hosts, the Package Manager and MCP Switches, and the Two Rules That Stop web_fetch
- Where the Orchestration Program Runs - Programmatic Tool Calling in the Claude and OpenAI APIs, and Code Mode in Agent Harnesses
References:
Tech Blog with curated related content
Written by Hidekazu Konishi