# MCP Python SDK v2.1.0

- Product: MCP Python SDK (https://whatsnew.fyi/product/mcp-python-sdk)
- Vendor: Anthropic
- Date: 2026-08-24
- Version: v2.1.0
- Original notes: https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.1.0
- Permalink: https://whatsnew.fyi/product/mcp-python-sdk/releases/v2.1.0

What's New is an index, not a publisher: every entry below links to the vendor's own release notes, which are the authoritative source. Entries are labelled where they are hand-curated sample data, pre-releases, or drawn from a secondary source such as a developer blog.

Reuse: the summaries, labels and curation here are © What's New. Quote freely with attribution and a link back; wholesale republication of the corpus is not permitted — terms: https://whatsnew.fyi/terms. The vendors' own release notes remain their publishers'.

---

- **added** — Client accepts StdioServerParameters directly
- **added** — Prompt messages accept Image and Audio
- **added** — Prompt functions may return bare content blocks
- **added** — Message, UserMessage, and AssistantMessage are exported from mcp.server.mcpserver
- **added** — SseServerTransport and MCPServer.sse_app() take max_request_body_size parameter
- **changed** — Handler exceptions from tool, resource or prompt handlers are logged once at ERROR with traceback, and client sees only Error executing message instead of exception text
- **changed** — Content-block return annotations no longer advertise outputSchema or return structuredContent for tools returning TextContent, EmbeddedResource, Image, Audio, or lists/unions of them
- **changed** — The 4 MiB request body limit now covers the SSE transport and OAuth endpoints
- **fixed** — TypedDict tool results with NotRequired keys are omitted instead of serialized as null
- **fixed** — TypedDict tool registration no longer fails on Python 3.10
- **fixed** — Recursive tool return types get an object-rooted outputSchema that pre-2026 clients accept
- **fixed** — POSTed notifications such as notifications/cancelled are acknowledged with 202 instead of 400 on 2026-07-28 HTTP entry
- **fixed** — Pre-2026 sessions ignore cache-hint fields from later revisions instead of failing list_tools()
- **fixed** — Pre-2026 sessions accept boolean sub-schemas in tool schema properties
- **fixed** — mcp install reads and preserves Claude Desktop config containing non-ASCII text on any Windows code page
- **fixed** — SSE message endpoint answers 405 to non-POST requests

##### 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 https://github.com/modelcontextprotocol/python-sdk/pull/3211
* Describe the maintenance line without hardcoding 1.28 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3212
* Ask which release line a bug report is on by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3213
* Link the released 2026-07-28 spec and point migrators at /v1/ by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3214
* Bump conformance harness to 0.2.0-alpha.11 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3282
* Read UTF-8 test fixtures with explicit encoding by @ShuQingDollarVoyager in https://github.com/modelcontextprotocol/python-sdk/pull/3245
* Pin each conformance leg to a spec-revision wire by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3304
* docs: publish translated docs in twelve languages and the tool that maintains them by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3280
* Pin text I/O to UTF-8 and fail CI on locale-dependent reads/writes by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3296
* docs: lead the README client example with a URL, not the server object by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3315
* Publish versioning, roadmap, and dependency policies for v2 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3215
* Drop later-revision cache-hint fields on pre-2026 sessions by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3223
* Stop framing breaking changes as a workflow in AGENTS.md by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3286
* MCPServer: content-block returns are unstructured, prompt messages take Image/Audio by @maxisbey in https://github.com

_[Truncated at 4000 characters — full notes: https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.1.0]_