Tracker: 2026-07-28 Spec Refactor #4857

Background

MCP spec 2026-07-28 is the biggest protocol revision so far:

• Stateless: no initialize handshake and no sessions. There is a new server/discover RPC.
• Multi Round-Trip Requests (MRTR) replace server-initiated sampling, elicitation and roots.
• subscriptions/listen replaces resource subscribe/unsubscribe.
• Tasks moved to an extension.
• Deprecated: Roots, Sampling, Logging and HTTP+SSE.

Both SDKs have shipped v2 lines that support it:

Today the reference servers are still on @modelcontextprotocol/sdk@^1.29 and mcp>=1.29,<2. The Python servers are pinned below 2 because v2 broke them (#4560, #4570, #4663).

This tracker supersedes the decomposition plan in #4475. PR #4452 (TS v2 alpha draft) is kept as a stale reference only.

Sub-issues

Wave 1: characterization tests of current behavior. Tests come first so we can prove the supposedly transparent SDK migrations really are transparent. The two can be worked in parallel.

• Bugs, Coverage, and SDK Wave 1 Part 1: TypeScript servers: extensive unit tests + per-file 90% coverage gate #4854 Part 1: TypeScript servers: extensive unit tests + per-file 90% coverage gate
• Bugs, Coverage, and SDK Wave 1 Part 2: Python servers: extensive unit tests + per-file 90% coverage gate #4855 Part 2: Python servers: extensive unit tests + per-file 90% coverage gate
• Adopt MCP interface-diff CI for the everything server (decide on PR #3260) #4860 Adopt MCP interface-diff CI for everything (decide on PR ci: add MCP interface diff workflow for Everything server #3260). This gives interface-level evidence that Part 3 is transparent.

Wave 2: fix the known bugs the Wave 1 suites pin. Wave 1's suites pin current behavior, bugs included, and every test that pins a bug is marked KNOWN BUG #N. This wave fixes those bugs in the legacy-era servers (SDK 1.x), changing each pinned assertion to the correct behavior. At the end, git grep "KNOWN BUG" is empty and every test asserts expected behavior, so the legacy servers are up to par before the migration.

• Bugs, Coverage, and SDK Wave 2: fix the known bugs the Wave 1 suites pin (legacy-era servers) #5004 Wave 2 tracker: 48 bug issues across the seven servers, after the Wave 1 PRs merge

Wave 3: migrate to the v2 SDKs. No wire behavior changes; the suites, as corrected in Wave 2, must pass with only import and type changes.

• Spec Refactor Wave 1 Part 1: Migrate TypeScript servers to TS SDK v2 (codemod) #4856 Part 3: Migrate TypeScript servers to TS SDK v2 (codemod), after Bugs, Coverage, and SDK Wave 1 Part 1: TypeScript servers: extensive unit tests + per-file 90% coverage gate #4854 and Bugs, Coverage, and SDK Wave 2: fix the known bugs the Wave 1 suites pin (legacy-era servers) #5004's TypeScript bugs (everything, filesystem, memory, sequentialthinking)
• Spec Refactor Wave 1 Part 2: Migrate Python servers to Python SDK v2 #4851 Part 4: Migrate Python servers to Python SDK v2, after Bugs, Coverage, and SDK Wave 1 Part 2: Python servers: extensive unit tests + per-file 90% coverage gate #4855 and Bugs, Coverage, and SDK Wave 2: fix the known bugs the Wave 1 suites pin (legacy-era servers) #5004's Python bugs (fetch, git, time)

Wave 4: modern-era servers. Serve 2026-07-28 and legacy clients from the same server, and extend the test suites to cover the new spec.

• Spec Refactor Wave 2 Part 1: Modern-era TypeScript servers + new features in everything #4852 Part 5: Modern-era TypeScript servers + new features in everything, after Spec Refactor Wave 1 Part 1: Migrate TypeScript servers to TS SDK v2 (codemod) #4856
• Spec Refactor Wave 2 Part 2: Modern-era Python servers #4853 Part 6: Modern-era Python servers, after Spec Refactor Wave 1 Part 2: Migrate Python servers to Python SDK v2 #4851

Part 1 (TS tests) ─┐                     ┌─► Part 3 (TS SDK v2) ──► Part 5 (TS modern era + new-spec tests)
                   ├─► #5004 (bug fixes) ┤
Part 2 (Py tests) ─┘                     └─► Part 4 (Py SDK v2) ──► Part 6 (Py modern era + new-spec tests)

Notes

• Branch: work lands on v2/main, per the v2 branch discipline in 2026-07-28 Spec Refactor Part 1: TypeScript Servers #4475. v2/main is currently behind main and must be brought up to date before Part 1 starts. Closes #N will not auto-close issues on a non-default branch, so close them by hand on merge and move the card to Done.
• Verification: every part is verified against both a 2026-07-28 client and a 2025-11-25 client, using the Inspector V2 and an LLM client.
• Coverage: the per-file 90% gate from Bring all servers to the 90% per-file coverage gate; reintroduce the rule to AGENTS.md #4474 (the inspector's gate) is established in Wave 1 and must hold through every later part.

References

• Spec changelog: https://modelcontextprotocol.io/specification/2026-07-28/changelog
• TS upgrade guide: https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration/upgrade-to-v2.md
• TS 2026-07-28 support: https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration/support-2026-07-28.md
• Python migration guide: https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/migration.md