docs/development/v4-notes/index.mdx
This directory is the working map of FastMCP v4.0: the complete register of user-facing changes from the MCP Python SDK v2 migration (PR #4437), plus the forward v4 feature program. It plays three roles at once.
mode="auto" default with a partial SDK-composition (#4572/#4574, full composition blocked upstream) have shipped; sampling removal and SDK delegation remain ahead. Each carries an explicit status in the Feature Program. The shipped side — what a v4 deployment provides on the modern protocol today, including the complete server-side SEP-990 identity assertion implementation — is cataloged in 2026-07-28 Protocol Support.FastMCP v4.0 is an engine swap. Three forces drive the major version:
The MCP Python SDK v2 rebuild. The SDK v2 makes two sweeping changes to the protocol layer: it splits the protocol types out of mcp.types into a standalone mcp_types package, and it renames every protocol field from camelCase to snake_case (inputSchema → input_schema, mimeType → mime_type, isError → is_error). It also rewrites the server request-handling model — handlers are now registered by method string and return bare result models, there is no request_ctx ContextVar, and server-side middleware is a first-class SDK concept. FastMCP absorbs almost all of this so that a typical server needs zero code changes.
Protocol version 2026-07-28. The SDK v2 serves multiple protocol eras from one server. Alongside the session-based handshake eras, it introduces the sessionless 2026-07-28 era, which discovers capabilities through server/discover and removes server-initiated requests (SEP-2577). This formally supersedes FastMCP's earlier "latest protocol only" stance: a single server now works with clients across the protocol transition.
Sampling removal. The 2026-07-28 era removes the server's ability to push a request back to the client mid-call. That takes the push-shaped sampling API (ctx.sample, ctx.sample_step) off the table on modern connections. Rather than leave it half-working, v4 deprecates it now and removes it in the 4.0 release — a real architectural shift for servers that borrowed the client's model, and one that justifies the major bump.
The migration merges to main and development continues there with subsequent PRs. Releases follow the SDK's own beta timeline:
main carries the beta pins. While the SDK is on mcp==2.0.0b1 / mcp-types==2.0.0b1, main cuts pre-releases (4.0.0b1, 4.0.0b2, …). No stable PyPI release goes out until mcp 2.0.0 reaches GA — at which point the pins swap to the stable SDK and 4.0.0 ships. The pin-swap is a tracked checklist item on the Known Gaps page.release/3.x is the maintenance line. A release/3.x branch is cut from pre-merge main. It stays on the SDK v1 line, receives upstream security patches, and serves users who cannot move to the SDK v2 beta yet.Following the pun-title convention (v<version>: <pun>), the v4 line runs a single "four" motif across the whole cycle, holding the headline name for the stable release the way v3 did ("Three at Last" for 3.0.0, stage puns for its betas):
| Release | Codename | The nod |
|---|---|---|
4.0.0a1 (alpha) | Fourst Contact | first contact — the first, cautious look at the new engine |
4.0.0b1 (beta) | Fourgone Conclusion | foregone conclusion — once the MCP SDK went v2, v4 was inevitable |
4.0.0 (stable) | Fast Fourward | fast forward — full speed onto the new foundation |
Each subsystem section in the Change Register tags its changes with one of four dispositions:
FastMCPDeprecationWarning. Users should migrate but are not forced to.The user-facing summary of the migration lives in the published Upgrading from FastMCP 3 guide. These development notes are the exhaustive version behind it.