You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A few defaults changed in this release. If you run a server or client on 2.x, skim these first:
Behaviour changes
HTTP client redirects are only followed within the endpoint's origin (#3397)
Client("https://..."), streamable_http_client and sse_client follow a redirect only if it stays on the same scheme, host and port (or upgrades http to https on the same host).
A redirect anywhere else is not followed: the call fails with MCPError and the session stays usable (an SSE connect fails with httpx2.HTTPStatusError). If that other URL is the server you meant, use it as the endpoint URL.
The follow_redirects setting on an httpx2.AsyncClient you pass in is no longer used for MCP requests, so you don't need it for the trailing-slash redirect any more.
The OAuth providers apply the same rule to their own requests.
Idle Streamable HTTP sessions now expire (legacy <=2025-11-25 spec( (#3395)
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.
Clients that keep the GET stream open (the SDK's Client does) are not affected. Neither are stateless servers or 2026-07-28 connections.
A server also holds at most 10 000 sessions at once; beyond that, new sessions get a 503.
To turn either off: mcp.run(transport="streamable-http", session_idle_timeout=None, max_sessions=None) (also on streamable_http_app() and run_streamable_http_async()).
The OAuth client checks the authorization server's issuer on the legacy path too (#3398)
For servers without protected resource metadata, authorization server metadata whose issuer isn't the server's own origin is now rejected with OAuthFlowError: Authorization server metadata issuer mismatch. The protected-resource-metadata path has done this since 2.0.
A 403 that isn't an insufficient_scope challenge is returned to the caller instead of retried.
If protected resource metadata can't be fetched because of a 5xx/429, the flow now stops instead of falling back to the legacy endpoints.
Prompt messages accept Image and Audio, prompt functions may return bare content blocks, and Message / UserMessage / AssistantMessage are exported from mcp.server.mcpserver (#3320).
The 4 MiB request body limit now also covers the SSE transport and the OAuth endpoints; SseServerTransport and MCPServer.sse_app() take max_request_body_size, and the SSE message endpoint answers 405 to non-POST requests (#3336).
Behaviour changes to be aware of
Handler exceptions (#3314): an unexpected exception from a tool, resource or prompt handler is logged once at ERROR with its traceback, and the client now sees only Error executing tool <name> (or the resource/prompt equivalent) rather than the exception text. Raise ToolError / ResourceError when the message is meant for the model; those still reach the client and are logged at INFO without a traceback.
Content-block return annotations (#3320): a tool annotated to return TextContent, EmbeddedResource, Image, Audio, or lists/unions of them no longer advertises outputSchema or returns structuredContent; its content is unchanged. Pass structured_output=True to keep the previous shape.
Fixes
TypedDict tool results: NotRequired keys are omitted instead of serialized as null, and registration no longer fails on Python 3.10 (#3224, #3227); recursive return types get an object-rooted outputSchema that pre-2026 clients accept (#3337).
2026-07-28 over HTTP: a POSTed notification such as notifications/cancelled is acknowledged with 202 instead of rejected with 400 (#3324).
Pre-2026 sessions ignore cache-hint fields from later revisions instead of failing list_tools() (#3223), and accept boolean sub-schemas in tool schema properties (#3353).
mcp install reads and preserves a Claude Desktop config containing non-ASCII text on any Windows code page (#3296).
What's Changed
Retire wording tied to pre-2.0 milestones by @maxisbey in #3211
Describe the maintenance line without hardcoding 1.28 by @maxisbey in #3212
Ask which release line a bug report is on by @maxisbey in #3213
Link the released 2026-07-28 spec and point migrators at /v1/ by @maxisbey in #3214
Bump conformance harness to 0.2.0-alpha.11 by @maxisbey in #3282
One off backport of the FastMCP import warning for 2.0.x, this is due to a lot of people running into this error and making issues on other repos about it. Ideally either pin mcp<2 or upgrade to 2.
What's Changed
[v2.0.x] Point imports of mcp.server.fastmcp at the migration guide by @maxisbey in #3393
This is v2.0.0, the stable v2 release of the MCP Python SDK. It supports the 2026-07-28 revision of the Model Context Protocol and serves every earlier revision from the same server. pip install mcp now installs 2.x.
pip install "mcp[cli]"# or
uv add "mcp[cli]"
Documentation Rewrite
The documentation has the full tutorial and API reference. Coming from v1? What's new in v2 is the tour of what changed and why, and the migration guide lists every breaking change with before-and-after code.
V1 Maintenance mode
v1.x is in maintenance mode and will only receive security fixes from now on The 1.x line lives on the v1.x branch, continues to receive critical bug fixes and security patches, and is documented at https://py.sdk.modelcontextprotocol.io/v1/. If your project is not ready to migrate, keep a <2 upper bound on your requirement (for example mcp>=1.28,<2).
Highlights
One SDK, both protocol eras
v2 speaks the 2026-07-28 revision (stateless requests with no handshake, server/discover, subscriptions/listen, multi-round-trip requests) and still serves every 2025-era client from the same MCPServer, over Streamable HTTP and stdio, with nothing to configure. Client(target) negotiates the version automatically.
FastMCP is now MCPServer, and there is a first-class Client
The decorator API is unchanged; the low-level Server is rebuilt around a shared dispatcher engine, and one Client object replaces v1's transport-plus-ClientSession-plus-initialize() layering. It connects to a URL, a stdio subprocess, a custom transport, or straight to a server object in memory for tests.
Multi-round-trip requests and resolver dependency injection
At 2026-07-28 the server can no longer call the client, so tools return the question instead. A Resolve(fn) parameter is filled by your function invisibly to the model and can put a question to the user; one tool body serves both eras.
Extension APIs, OpenTelemetry, and a standalone types package
Servers and clients compose protocol extensions through pluggable extension APIs (MCP Apps built in); OpenTelemetry tracing ships on by default; every protocol type is its own package, mcp-types (imported as mcp_types), published in lock-step with mcp.
Hardened stdio and auth
stdio servers keep handler subprocesses and stray prints off the wire, and stdout is diverted to stderr while serving. OAuth adds RFC 9207 issuer validation, the SEP-990 identity-assertion flow, and the client-credentials extension.
Coming from a v2 pre-release
Since the last release candidate: the per-version wire packages are private (mcp_types._v*), mcp.types is a permanent alias for mcp_types, the auth registration request model is split from the registered-client record, cancelled requests are no longer answered, and log notifications are gated on the per-request log-level opt-in at 2026-07-28. Since the betas: Client(cache=False) is now cache=None with CacheConfig() the default; Context.client_id, RFC7523OAuthClientProvider, and OAuthClientProvider(timeout=) are removed; the client-credentials providers take scope=; message_handler receives notifications and exceptions only; FileResource(is_binary=) becomes encoding; MCP_* env vars are gone with pydantic-settings; Streamable HTTP servers reject bodies over 4 MiB with HTTP 413. The migration guide covers all of it.
Known gaps
The tasks extension (SEP-2663) is not part of this release. On the client, the DPoP proof binding (SEP-1932) and the workload-identity jwt-bearer grant are not implemented; both are additive and can land in 2.x.
mcp is only a dev pin in clients/hermes. At runtime the plugin uses the mcp its host Hermes provides, and hermes-agent 0.18.2 and 0.19.0 both pin mcp==1.26.0 in their mcp extra. Porting the plugin to the v2 API (for example, ServerNotificationType is gone from mcp.types) would break it on the version the host actually runs.
Leaving this open for Renovate to rebase until hermes-agent supports mcp 2.x.
Holding this open: it is blocked by the host, not by our code.
The mcp SDK is not a runtime dependency of the Hermes adapter. The host hermes-agent provides it, and hermes-agent 0.19.0 pins mcp==1.26.0 exactly. The dev-group pin exists so the tests run against the SDK the host ships. Moving it to 2.x would test against a version the adapter never runs on, and porting commy/session.py to the v2 API (ServerNotificationType is gone) would break the adapter inside the real host.
Revisit once hermes-agent moves to mcp 2.x.
This branch has not been deployed
No deployments
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
GraemeF
added
question
This PR contains the following updates:
==1.30.0→==2.2.0Release Notes
modelcontextprotocol/python-sdk (mcp)
v2.2.0Compare Source
pip install -U mcp. Docs: https://py.sdk.modelcontextprotocol.io/A few defaults changed in this release. If you run a server or client on 2.x, skim these first:
Behaviour changes
HTTP client redirects are only followed within the endpoint's origin (#3397)
Client("https://..."),streamable_http_clientandsse_clientfollow a redirect only if it stays on the same scheme, host and port (or upgradeshttptohttpson the same host).MCPErrorand the session stays usable (an SSE connect fails withhttpx2.HTTPStatusError). If that other URL is the server you meant, use it as the endpoint URL.follow_redirectssetting on anhttpx2.AsyncClientyou pass in is no longer used for MCP requests, so you don't need it for the trailing-slash redirect any more.Idle Streamable HTTP sessions now expire (legacy <=2025-11-25 spec( (#3395)
Clientdoes) are not affected. Neither are stateless servers or 2026-07-28 connections.mcp.run(transport="streamable-http", session_idle_timeout=None, max_sessions=None)(also onstreamable_http_app()andrun_streamable_http_async()).The OAuth client checks the authorization server's
issueron the legacy path too (#3398)issuerisn't the server's own origin is now rejected withOAuthFlowError: Authorization server metadata issuer mismatch. The protected-resource-metadata path has done this since 2.0.insufficient_scopechallenge is returned to the caller instead of retried.Two new
MCPDeprecationWarnings (#3435, #3447)ClientCredentialsOAuthProvider/PrivateKeyJWTOAuthProviderwithoutissuer=. Pass your authorization server's issuer URL; 3.0 will require it.AuthSettingswithresource_server_urlset butvalidate_token_resourceunset. Set it toTrueorFalse; 3.0 defaults it toTrue.New
AuthSettings.validate_token_resource: only accept tokens yourTokenVerifierreports as issued for this server (#3447).issuer=onClientCredentialsOAuthProviderandPrivateKeyJWTOAuthProvider(#3398).session_idle_timeout=andmax_sessions=on the Streamable HTTP server entry points (#3395).Fixes
DELETEfrees its session immediately, and a refused opening request no longer leaves a session behind (#2455, #3228, #3300).$refs in a tool'soutputSchemaresolve within that schema only; an unresolvable one surfaces asRuntimeError: Invalid schema for tool ...(#3394).Known gaps
The tasks extension (SEP-2663), DPoP (SEP-1932) and the
jwt-bearergrant are not implemented yet; https://github.com/modelcontextprotocol/python-sdk/blob/main/ROADMAP.md tracks them.What's Changed
Full Changelog: modelcontextprotocol/python-sdk@v2.1.1...v2.2.0
v2.1.1Compare Source
What's Changed
Full Changelog: modelcontextprotocol/python-sdk@v2.1.0...v2.1.1
v2.1.0Compare Source
Highlights
ClientacceptsStdioServerParametersdirectly:Client(StdioServerParameters(command="uv", args=["run", "server.py"]))(#3321).ImageandAudio, prompt functions may return bare content blocks, andMessage/UserMessage/AssistantMessageare exported frommcp.server.mcpserver(#3320).SseServerTransportandMCPServer.sse_app()takemax_request_body_size, and the SSE message endpoint answers 405 to non-POST requests (#3336).Behaviour changes to be aware of
Error executing tool <name>(or the resource/prompt equivalent) rather than the exception text. RaiseToolError/ResourceErrorwhen the message is meant for the model; those still reach the client and are logged at INFO without a traceback.TextContent,EmbeddedResource,Image,Audio, or lists/unions of them no longer advertisesoutputSchemaor returnsstructuredContent; itscontentis unchanged. Passstructured_output=Trueto keep the previous shape.Fixes
NotRequiredkeys are omitted instead of serialized asnull, and registration no longer fails on Python 3.10 (#3224, #3227); recursive return types get an object-rootedoutputSchemathat pre-2026 clients accept (#3337).notifications/cancelledis acknowledged with 202 instead of rejected with 400 (#3324).list_tools()(#3223), and accept boolean sub-schemas in tool schemaproperties(#3353).mcp installreads and preserves a Claude Desktop config containing non-ASCII text on any Windows code page (#3296).What's Changed
New Contributors
Full Changelog: modelcontextprotocol/python-sdk@v2.0.0...v2.1.0
v2.0.1Compare Source
One off backport of the FastMCP import warning for
2.0.x, this is due to a lot of people running into this error and making issues on other repos about it. Ideally either pinmcp<2or upgrade to 2.What's Changed
Full Changelog: modelcontextprotocol/python-sdk@v2.0.0...v2.0.1
v2.0.0Compare Source
MCP Python SDK v2 Stable Release
This is v2.0.0, the stable v2 release of the MCP Python SDK. It supports the 2026-07-28 revision of the Model Context Protocol and serves every earlier revision from the same server.
pip install mcpnow installs 2.x.Documentation Rewrite
The documentation has the full tutorial and API reference. Coming from v1? What's new in v2 is the tour of what changed and why, and the migration guide lists every breaking change with before-and-after code.
V1 Maintenance mode
v1.x is in maintenance mode and will only receive security fixes from now on The 1.x line lives on the
v1.xbranch, continues to receive critical bug fixes and security patches, and is documented at https://py.sdk.modelcontextprotocol.io/v1/. If your project is not ready to migrate, keep a<2upper bound on your requirement (for examplemcp>=1.28,<2).Highlights
One SDK, both protocol eras
v2 speaks the 2026-07-28 revision (stateless requests with no handshake,
server/discover,subscriptions/listen, multi-round-trip requests) and still serves every 2025-era client from the sameMCPServer, over Streamable HTTP and stdio, with nothing to configure.Client(target)negotiates the version automatically.FastMCPis nowMCPServer, and there is a first-classClientThe decorator API is unchanged; the low-level
Serveris rebuilt around a shared dispatcher engine, and oneClientobject replaces v1's transport-plus-ClientSession-plus-initialize()layering. It connects to a URL, a stdio subprocess, a custom transport, or straight to a server object in memory for tests.Multi-round-trip requests and resolver dependency injection
At 2026-07-28 the server can no longer call the client, so tools return the question instead. A
Resolve(fn)parameter is filled by your function invisibly to the model and can put a question to the user; one tool body serves both eras.Extension APIs, OpenTelemetry, and a standalone types package
Servers and clients compose protocol extensions through pluggable extension APIs (MCP Apps built in); OpenTelemetry tracing ships on by default; every protocol type is its own package,
mcp-types(imported asmcp_types), published in lock-step withmcp.Hardened stdio and auth
stdio servers keep handler subprocesses and stray prints off the wire, and stdout is diverted to stderr while serving. OAuth adds RFC 9207 issuer validation, the SEP-990 identity-assertion flow, and the client-credentials extension.
Coming from a v2 pre-release
Since the last release candidate: the per-version wire packages are private (
mcp_types._v*),mcp.typesis a permanent alias formcp_types, the auth registration request model is split from the registered-client record, cancelled requests are no longer answered, and log notifications are gated on the per-request log-level opt-in at 2026-07-28. Since the betas:Client(cache=False)is nowcache=NonewithCacheConfig()the default;Context.client_id,RFC7523OAuthClientProvider, andOAuthClientProvider(timeout=)are removed; the client-credentials providers takescope=;message_handlerreceives notifications and exceptions only;FileResource(is_binary=)becomesencoding;MCP_*env vars are gone withpydantic-settings; Streamable HTTP servers reject bodies over 4 MiB with HTTP 413. The migration guide covers all of it.Known gaps
The tasks extension (SEP-2663) is not part of this release. On the client, the DPoP proof binding (SEP-1932) and the workload-identity
jwt-bearergrant are not implemented; both are additive and can land in 2.x.Feedback
Something rough, confusing, or broken? Open an issue or find us in #python-sdk-dev on the MCP Contributors Discord.
Full Changelog: modelcontextprotocol/python-sdk@v2.0.0rc1...v2.0.0
Configuration
📅 Schedule: (UTC)
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about this update again.
This PR was generated by Mend Renovate. View the repository job log.