PR #3054 - modelcontextprotocol/python-sdk

Add a single new page, What's new in v2 (docs/whats-new.md), that gives someone glancing at the v2 beta the high-level tour in two halves: what changed in the SDK between v1 and v2, and what the 2026-07-28 protocol revision changes as this SDK surfaces it. Every section is a few sentences plus a link to the page that owns the topic.

Motivation and Context

The docs have a complete Migration Guide (about 1,700 lines, exhaustive by design) and, since the restructure, a page per topic, but nothing that answers the first question an upgrader or evaluator has: what is new, and why should I care? The v2.0.0b1 release notes answer that well for one release; this page is the durable, ranked version of that story inside the docs, written for someone who builds MCP servers or clients, not for a spec reader.

The page's shape (mirroring the two-part structure the v2.0.0b1 release notes already use):

The SDK: v1 to v2: the FastMCP to MCPServer rename (and what did not change), the new first-class Client, the rebuilt low-level Server, the mcp-types split plus snake_case fields, transport configuration moving to run(), the behavior changes that arrive without an import error, and the removals.
The protocol: 2025-11-25 to 2026-07-28: no handshake and no session (and what that means for deployment, stated with its honest qualifiers), multi-round-trip requests replacing server-initiated requests (with the one "your tests hit this first" warning), the SEP-2577 deprecations plus the ping removal, subscriptions/listen, and a short list of the rest (routing headers, cache hints, error codes, auth hardening, extensions, OpenTelemetry).
Upgrading from v1?: the Migration Guide, the v1.x maintenance posture, and the v2 feedback template.

Two editorial rules were enforced throughout, because a page like this fails by overclaiming: nothing v1 already had is presented as v2 news, and every protocol fact carries its honest scope (stateless_http is a legacy-leg-only option and is not why 2026-07-28 traffic is sessionless; the client-side subscriptions/listen driver is not shipped yet; the tasks extension is not implemented yet).

Two behavior changes the page states had no entry in the Migration Guide, so this PR also adds them there (short sections, per the repository's own rule that behavior changes are documented in docs/migration.md): synchronous def handlers now run on a worker thread, and mcp dev / mcp install now pin the environment they spawn to the installed SDK version.

Also in this PR, so the page is discoverable: a nav entry (top level, right after the index), a link from the docs home page and the README, and the page's path added to the docs example linter's allowlist so its fenced code is ruff-checked in CI like every other page's.

How Has This Been Tested?

mkdocs build --strict is clean, and under strict mode a broken link, a broken anchor (including the eight migration.md#... deep links the page makes), a bad --8<-- include, and a page missing from the nav are each a build failure.
The docs test suites pass: 976 tests (from 973; the three new cases are the new page's fenced blocks, now linted by tests/test_examples.py). The page adds no new docs_src/ files: its two runnable examples are existing, already-tested files included from a second page.
./scripts/test (coverage, branch mode, fail_under = 100) passes, and all pre-commit hooks pass.
Every factual claim on the page was checked against the code at both origin/v1.x and main (not against other docs), then independently re-checked, and the rendered site was exercised end to end: the page renders with both includes resolved, the nav and home-page links land on it, every migration.md anchor it links exists in the built HTML, and the llms.txt build hook picks it up.

Breaking Changes

None. Documentation only.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

The page deliberately carries almost no code of its own: one three-line rename fence and two --8<-- includes of existing tested examples. Everything else is prose that ends in a link to the page that owns the topic, so there is no second copy of any explanation to drift.
The page intentionally has no version pin: RELEASE.md keeps a list of the files that carry the release pin, and this page stays off it by linking Installation instead.
Nav placement (a top-level entry right after the home page) is an editorial call: the target reader is someone evaluating the beta, and the home page's banner now routes them here. Happy to move it next to the Migration Guide at the bottom instead if that grouping is preferred.

_{AI Disclaimer}