MCP Python SDK 2.3.0 and 1.30.0: latest versions, API diff and gotchas

MCP Python SDK 2.3.0 (2026-10-02 22:02 UTC)

• Expose max_sse_event_size option on Streamable HTTP client transports and StreamableHttpParameters, defaulting to 1 MiB per SSE event. (source)
• Reject a tool with an invalid x-mcp-header annotation at registration with InvalidSignature. (source)
• Allow MCPServer(subscriptions=False) to stop serving subscriptions/listen and advertise subscriptions as disabled. (source)
• Client.call_tool re-lists tools and retries once after a HeaderMismatch (-32020) rejection. (source)
• Omit empty _meta and empty params from outbound requests on pre-2026 connections. (source)
• Stop counting interactive OAuth login wait time against client request timeouts. (source)
• Server(get_tool_input_schema=...) allows direct tool schema lookup for header validation without invoking tools/list. (source)

MCP Python SDK 2.2.0 (2026-09-07 15:53 UTC)

• HTTP client transports follow redirects only within the endpoint's origin (scheme, host and port). (source)
• On legacy (<=2025-11-25) connections, idle stateful Streamable HTTP sessions expire after 30 minutes; concurrent sessions are capped at 10,000, while 2026-07-28 connections are not affected. (source)
• Validate authorization server metadata issuer on every discovery path, rejecting mismatches with OAuthFlowError. (source)
• Add AuthSettings.validate_token_resource to verify bearer tokens are issued for this server. (source)
• Deprecate constructing ClientCredentialsOAuthProvider and PrivateKeyJWTOAuthProvider without an issuer. (source)

MCP Python SDK 1.30.0 (2026-09-07 14:03 UTC)

• v1.x: HTTP client transports follow redirects only within the endpoint's origin, raising httpx.HTTPStatusError otherwise. (source)
• v1.x: idle stateful Streamable HTTP sessions with nothing in flight expire after 30 minutes, and concurrent sessions are capped at 10,000 via session_idle_timeout and max_sessions on FastMCP. (source)
• v1.x: authorization server issuer validation on discovery with OAuthFlowError. (source)
• v1.x: AuthSettings.validate_token_resource option added. (source)
• v1.x: resolve tool output-schema $ref references within the schema document only. (source)

MCP Python SDK 2.0.1 (2026-08-26 10:42 UTC)

• Backported custom ModuleNotFoundError for imports of mcp.server.fastmcp pointing to the v2 migration guide. (source)

MCP Python SDK 2.1.1 (2026-08-25 15:58 UTC)

• Point imports of mcp.server.fastmcp at the v2 migration guide with actionable ModuleNotFoundError. (source)

MCP Python SDK 2.2.0 → 2.3.0

1 export added, 0 removed, 7 exports with parameter or option changes; 20 source files changed.

Method: bin/sandbox-run installed both versions in a throwaway Linux sandbox (mac arm64, Python 3.13.5) and compared all exported symbols and signatures across all entry points (188 and 189 exported symbols). In the tables, "command" is an exported symbol or class and "flags" are public parameters or options.

Exports added:

• mcp.client.streamable_http DEFAULT_MAX_SSE_EVENT_SIZE

• v2 line: mcp at the latest two minor releases (2.2.0 and 2.3.0). Total exports increased from 188 to 189.
• DEFAULT_MAX_SSE_EVENT_SIZE = 1048576 (1 MiB) added to mcp.client.streamable_http; StreamableHTTPTransport and streamable_http_client take max_sse_event_size: int | None = 1048576.
• MCPServer constructor parameter subscriptions now accepts Literal[False] to stop serving subscriptions/listen and advertise subscriptions as disabled.
• Server constructor adds get_tool_input_schema callback to allow direct tool schema lookup during Mcp-Param-* header validation without invoking the tools/list handler.
• Tool registration via @mcp.tool() now validates x-mcp-header parameter types, rejecting anything other than plain int/str/bool with InvalidSignature.
• Outbound requests on pre-2026 connections omit empty _meta: {} and empty params.

`from mcp.server.fastmcp import FastMCP` raises ModuleNotFoundError in 2.x (MCP Python SDK 2.3.0)

python3 -c "from mcp.server.fastmcp import FastMCP"

fastmcp import failed: ModuleNotFoundError: No module named 'mcp.server.fastmcp'. This is mcp 2.x, where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer) and other APIs changed; see the migration guide at https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver or pin 'mcp<2' to keep running v1 code.

Fix: Import MCPServer from mcp.server.mcpserver (or mcp.server): from mcp.server.mcpserver import MCPServer. If your project cannot migrate yet, pin pip install "mcp>=1.28,<2". (source)

Fix page: /fixes/mcp-python-no-module-fastmcp

Invalid `x-mcp-header` annotation raises InvalidSignature during tool registration (MCP Python SDK 2.3.0)

from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver import MCPServer
server = MCPServer("test")
@server.tool()
def greet(region: Annotated[list[str], Field(json_schema_extra={"x-mcp-header": "Region"})]) -> str:
    return "hello"

tool registration failed: InvalidSignature: Tool 'greet' has an invalid x-mcp-header annotation: property 'region': x-mcp-header is only permitted on integer/string/boolean properties (got 'array')

Fix: Use only plain str, int, or bool parameters for header bindings. For optional string headers, declare the schema explicitly using WithJsonSchema({"type": "string", "x-mcp-header": "Header-Name"}). (source)

`max_sse_event_size` must be positive or None on StreamableHTTPTransport (MCP Python SDK 2.3.0)

from mcp.client.streamable_http import StreamableHTTPTransport
transport = StreamableHTTPTransport("http://127.0.0.1:8000/mcp", max_sse_event_size=0)

transport creation failed: ValueError: max_sse_event_size must be positive or None

Fix: Pass a positive integer byte limit (default is 1048576, 1 MiB) or pass max_sse_event_size=None to disable the event size cap for large tool results. (source)

2026-10: v2 2.3.0 (2026-10-02)

• 2.3.0 (2026-10-02): max_sse_event_size on Streamable HTTP client transports, x-mcp-header annotation validation at tool registration, MCPServer(subscriptions=False) opt-out, tool call retry on HeaderMismatch, and empty _meta / params omission. (source)

2026-09: v2 2.2.0; v1.x 1.30.0 (2 versions)

• 2.2.0 and 1.30.0 (2026-09-07): same-origin redirect restriction on HTTP client transports, 30-minute idle expiration for stateful legacy sessions, authorization server issuer validation on discovery, and AuthSettings.validate_token_resource. (source)

2026-08: v2 2.0.1 to 2.1.1; v1.x 1.29.1 (4 versions)

• 2.1.0 (2026-08-24): Client takes StdioServerParameters directly, Image/Audio support in prompt messages, 4 MiB body limit on SSE/OAuth endpoints, and handler exceptions logged without wire traceback leaks. (source)
• 2.0.1 (2026-08-26) and 2.1.1 (2026-08-25): added migration guide pointer on mcp.server.fastmcp imports. (source)
• 1.29.1 (2026-08-24): FastMCP settings initialization fix and 4 MiB request body limits on SSE/OAuth endpoints in v1.x. (source)

2026-07: v2 2.0.0 (stable 2026-07-28); v1.x 1.29.0

• 2.0.0 (2026-07-28): stable v2 release supporting the 2026-07-28 protocol revision, MCPServer replacing FastMCP, first-class Client, standalone mcp-types package, and resolver dependency injection. (source)
• 1.29.0 (2026-07-28): v1 maintenance release setting up v1.x branch support. (source)

2026-06: v1.x 1.28.0 to 1.28.1; v2 prereleases

• 1.28.0 (2026-06-16) and 1.28.1 (2026-06-26): v1 maintenance line updates for stdio transport buffering and roots list changes. (source)

2026-05: v1.x 1.27.1 to 1.27.2

• 1.27.1 (2026-05-08) and 1.27.2 (2026-05-29): v1 updates for server lifespan contexts and SSE reconnection handling. (source)