modelcontextprotocol/python-sdk v2.1.0

on GitHub

Highlights

• Client accepts StdioServerParameters directly: Client(StdioServerParameters(command="uv", args=["run", "server.py"])) (#3321).
• 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
• Read UTF-8 test fixtures with explicit encoding by @ShuQingDollarVoyager in #3245
• Pin each conformance leg to a spec-revision wire by @maxisbey in #3304
• docs: publish translated docs in twelve languages and the tool that maintains them by @maxisbey in #3280
• Pin text I/O to UTF-8 and fail CI on locale-dependent reads/writes by @maxisbey in #3296
• docs: lead the README client example with a URL, not the server object by @maxisbey in #3315
• Publish versioning, roadmap, and dependency policies for v2 by @maxisbey in #3215
• Drop later-revision cache-hint fields on pre-2026 sessions by @maxisbey in #3223
• Stop framing breaking changes as a workflow in AGENTS.md by @maxisbey in #3286
• MCPServer: content-block returns are unstructured, prompt messages take Image/Audio by @maxisbey in #3320
• Let Client take StdioServerParameters directly by @maxisbey in #3321
• Gate external PRs on an assigned, linked issue by @maxisbey in #3291
• docs: cover the remaining Tier 1 audit items by @maxisbey in #3325
• Acknowledge notification POSTs with 202 on the 2026-07-28 HTTP entry by @maxisbey in #3326
• Shorten stdio test comments by @Kludex in #3329
• Hand TypedDict tool results to pydantic natively by @maxisbey in #3331
• Apply the request body limit to the SSE and OAuth endpoints by @maxisbey in #3336
• Accept boolean sub-schemas in 2025-11-25 tool schema properties by @pja-ant in #3354
• Log MCPServer handler exceptions by kind and keep crash details off the wire by @maxisbey in #3314
• Give recursive tool return types an object-rooted output schema by @maxisbey in #3376
• docs: refresh translations for recent English changes by @maxisbey in #3379
• Build releases with the pinned hatchling and a publish action that accepts Metadata 2.5 by @maxisbey in #3380

New Contributors

• @ShuQingDollarVoyager made their first contribution in #3245

Full Changelog: v2.0.0...v2.1.0