docs: add a "What's new in v2" page#3054
Conversation
Add docs/whats-new.md, a two-part tour for someone glancing at the v2 beta: the v1 -> v2 SDK changes (the MCPServer rename and what did not change, the first-class Client, the rebuilt low-level Server, the mcp-types split and snake_case fields, transport configuration moving to run(), the behavior changes that arrive without an import error, and the removals) and the 2025-11-25 -> 2026-07-28 protocol changes as this SDK surfaces them (no handshake or session and what that means for deployment, multi-round-trip requests replacing server-initiated requests, the SEP-2577 deprecations and the ping removal, subscriptions/listen, and the smaller items). Every section ends in a link to the page that owns the topic; the only code is one rename fence plus two existing, already tested docs_src includes. Wire the page up: a top-level nav entry right after the index, links from the docs home page and the README, and the page's path in the docs example linter's allowlist so its fenced code is ruff-checked in CI. Two behavior changes the page states had no entry in the migration guide, so add them there too: sync def handlers now run on a worker thread (Breaking Changes), and mcp dev / mcp install now pin the spawned environment to the installed SDK version (Bug Fixes).
📚 Documentation preview
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
No issues found across 6 files
Tip: cubic could auto-approve low-risk PRs like this, if it thinks it's safe to merge. Learn more
Re-trigger cubic
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
No issues found — but this adds a substantial new user-facing docs page with many specific claims about SDK/protocol behavior, plus an explicitly-open editorial call on nav placement, so it deserves a maintainer read.
Extended reasoning...
Overview
Docs-only PR: a new ~140-line docs/whats-new.md page, a nav entry in mkdocs.yml, links from README.md and docs/index.md, two new sections in docs/migration.md (sync handlers on worker threads; mcp dev/mcp install version pinning), and the new page added to the tests/test_examples.py docs-lint allowlist. No source code under src/ is touched.
Security risks
None. No executable code changes; the only test change adds a path to an existing allowlist so the page's fenced code is ruff-linted in CI.
Level of scrutiny
The change carries no runtime risk, but it is a prominent, front-of-nav page making dozens of concrete technical claims about v2 behavior (error codes, NoBackChannelError semantics, subscriptions/listen caveats, deployment guidance around request_state keys, SEP references). The claims I cross-checked against the migration guide and repo conventions are consistent, and the author reports mkdocs build --strict and the docs test suites pass, but full factual verification of every claim is exactly the kind of editorial review a maintainer should do for a page this visible. The PR description also explicitly leaves the nav placement decision open for maintainer preference.
Other factors
The two new migration-guide sections document behavior changes per the repository's own rule, which is appropriate scope for this PR. The page reuses existing tested docs_src/ examples rather than adding new ones, keeping drift risk low. No prior reviews or comments exist on this PR.
Show the same one-tool server written for v1 and for v2 in the 'rebuilt, not renamed' section, with code annotations carrying the contrasts: how the request context is reached (ambient ContextVar vs the ctx argument), return wrapping (bare lists vs full result models), argument validation (enforced jsonschema in v1 vs advertised-only in v2), exception polarity (isError=True text the model reads vs a sanitized -32603 protocol error), and registration (decorators vs constructor arguments). The v2 half is a tested file, docs_src/whats_new/tutorial001.py, driven end to end by tests/docs_src/test_whats_new.py (schema advertised verbatim; a call missing a required argument reaches the handler and comes back as the sanitized protocol error). The v1 half cannot import in CI, so it stays an inline fence with a comment recording its ground truth: the exact code was run verbatim against a real mcp==1.28.1 install.
One call_tool handler serves every tool, so both halves of the before/after now check the name, and the check doubles as the live demo of the error-polarity contrast: v1 raises ValueError because the message comes back as CallToolResult(isError=True) text the model reads; v2 raises MCPError(INVALID_PARAMS, ...) because a bare exception would be sanitized to -32603, and -32602 with this message is the spec's own answer for an unknown tool. New test proves the raised MCPError passes through with code and message intact.
Surface the Resolve dependency interface in the SDK half as the preferred way to ask the client for input mid-call (era-portable: live elicitation for legacy clients, multi-round-trip on 2026-07-28), with a note that ctx.elicit() for legacy connections and hand-built InputRequiredResult remain, each pointing at its owning page.
There was a problem hiding this comment.
No issues found in the code-facing parts of this PR — the new docs_src example and its tests follow the repo's patterns, and I verified the two new migration-guide claims (sync handlers via anyio.to_thread.run_sync, mcp dev/install pinning via mcp_requirement()) against the source. Deferring to a human since the bulk of this PR is a large editorial page whose factual claims and nav placement (which you explicitly flag as an open question) are a maintainer's call.
Extended reasoning...
Overview
This PR is documentation-only: a new ~210-line "What's new in v2" page (docs/whats-new.md), two new sections in docs/migration.md (sync handlers on a worker thread; mcp dev/install version pinning), links from README.md and docs/index.md, an mkdocs nav entry, one new tested example (docs_src/whats_new/tutorial001.py) with a matching test file, and an addition to the docs example linter's allowlist. No runtime library code is touched.
Security risks
None. No source code under src/ changes; the only executable additions are a docs example and its tests.
Level of scrutiny
The code-adjacent pieces are small and check out: the new example follows the low-level Server pattern documented in the migration guide, the tests use the in-memory Client pattern the repo prescribes, and I verified the two new migration-guide behavior claims against the source (anyio.to_thread.run_sync in the mcpserver handlers/resolvers, and mcp_requirement() pinning in src/mcp/cli/claude.py). The bulk of the PR, however, is a long editorial page making many behavioral and protocol claims; while the author describes a thorough verification process, a page of this scope and prominence (top-level nav, linked from the README banner) warrants a maintainer's editorial review rather than a bot approval.
Other factors
The author explicitly asks for maintainer input on nav placement (top-level entry vs. next to the Migration Guide), which is an open design question only a human can settle. No bugs were found by the automated review, and there are no outstanding reviewer comments. mkdocs strict mode and the docs test suites reportedly cover link/anchor/include integrity in CI.
2 participants
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):
FastMCPtoMCPServerrename (and what did not change), the new first-classClient, the rebuilt low-levelServer, themcp-typessplit plus snake_case fields, transport configuration moving torun(), the behavior changes that arrive without an import error, and the removals.pingremoval,subscriptions/listen, and a short list of the rest (routing headers, cache hints, error codes, auth hardening, extensions, OpenTelemetry).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_httpis a legacy-leg-only option and is not why 2026-07-28 traffic is sessionless; the client-sidesubscriptions/listendriver 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): synchronousdefhandlers now run on a worker thread, andmcp dev/mcp installnow 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 --strictis clean, and under strict mode a broken link, a broken anchor (including the eightmigration.md#...deep links the page makes), a bad--8<--include, and a page missing from the nav are each a build failure.tests/test_examples.py). The page adds no newdocs_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.origin/v1.xandmain(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, everymigration.mdanchor it links exists in the built HTML, and thellms.txtbuild hook picks it up.Breaking Changes
None. Documentation only.
Types of changes
Checklist
Additional context
--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.RELEASE.mdkeeps a list of the files that carry the release pin, and this page stays off it by linking Installation instead.AI Disclaimer