v4.0.3: Once Is Enough

Multi-server clients with legacy-only backends now avoid unnecessary startup retries, and tools returning unconstrained sequences no longer send images twice. This patch also fixes task timing values rejected by strict clients and cleans up unfinished Monty callbacks when execution ends.

What's Changed

Enhancements ✨

• ci: deploy docs through Mintlify's admin API and wait for a verdict by @zzstoatzz in #4996
• perf: avoid duplicate startup for mixed-era backends by @ningmao-hlyz in #4971
• docs: clarify release title history lookup by @zzstoatzz in #5006

Fixes 🐞

• fix: don't infer an output schema for unconstrained sequences by @fsecada01 in #4999
• Clean up unfinished Monty callbacks by @zzstoatzz in #5005
• Fix task timing field serialization by @LarryHu0217 in #5003

Docs 📚

• docs: point What's New at the changelog for later releases by @zzstoatzz in #4992
• docs: attribute the back-channel removal to SEP-2322/2575, not SEP-2577 by @zzstoatzz in #4988
• docs: add v4.0.3 changelog entries by @zzstoatzz in #5007

New Contributors

• @fsecada01 made their first contribution in #4999
• @ningmao-hlyz made their first contribution in #4971

Full Changelog: v4.0.2...v4.0.3

v4.0.2: Root Access

ClientGroup is now importable from the package root, from fastmcp import ClientGroup, with the same lazy export and install hint as Client, so integrations no longer couple to FastMCP's internal module layout.

What's Changed

Enhancements ✨

• Expose ClientGroup from package root by @jlowin in #4987
• skills: add release skill with changelog entry helper by @zzstoatzz in #4982

Fixes 🐞

• docs: escape <1 in changelog so MDX parses by @zzstoatzz in #4978

Docs 📚

• docs: note the 4.0.1 floor for ClientGroup reentrancy by @zzstoatzz in #4980
• docs: link the GA announcement and blog from What's New by @zzstoatzz in #4984

Other Changes 🦾

• docs: add v4.0.2 changelog entries by @zzstoatzz in #4990

Full Changelog: v4.0.1...v4.0.2

v4.0.1: Come Back Any Time

ClientGroup now reference-counts its context the way Client does, so entering a connected group from a nested block or a concurrent task reuses the existing connections instead of raising. Adapters written against Client's reentrancy can hold a ClientGroup the same way.

What's Changed

Fixes 🐞

• ci: fix the published-docs PR step's working base by @zzstoatzz in #4960
• client: make ClientGroup context reentrant by @zzstoatzz in #4975

Docs 📚

• docs: update banner for FastMCP 4 GA by @zzstoatzz in #4958
• docs: correct whats-new and upgrade guide for GA by @zzstoatzz in #4961
• docs: drop prerelease install framing from installation and SDK migration guides by @zzstoatzz in #4963
• docs: refresh sidebar tags and fix audit findings by @zzstoatzz in #4965

Other Changes 🦾

• docs: add v4.0.1 changelog entries by @zzstoatzz in #4976

Full Changelog: v4.0.0...v4.0.1

v4.0.0: Four Real

FastMCP 4 is stable. Five betas, five weeks, 23 contributors, and more than 80 pull requests later — the new protocol engine held up under real gateways, agent frameworks, and production servers, and most FastMCP 3 applications upgrade without code changes.

This is the FastMCP release for the new MCP. On July 28, MCP released the 2026-07-28 protocol revision and the rewritten Python SDK v2 shipped the same day. FastMCP 4 is built on both: modern requests are sessionless and self-contained, so any replica behind an ordinary load balancer can answer them, and one FastMCP 4 deployment negotiates the best protocol version per connection — new clients get the new protocol, old clients keep working, and Client(url) does the same negotiation from the other side.

The new protocol's capabilities come through FastMCP's usual high-level surfaces:

• Interactive tools return a request for input — approval, a missing field — and re-run with the client's answers available on the context.
• Background tasks (@mcp.tool(task=True)) run outside the request path via the io.modelcontextprotocol/tasks extension, shipped in the optional fastmcp-tasks package on the same Docket engine as FastMCP 3.
• Extensions register with add_extension(): a negotiated capability, additive request methods, tool-call interception, and a lifespan. Tasks are built this way, outside core.
• Argument completion for prompt and resource-template inputs, with already-supplied arguments visible to the handler.
• Auth for agents and services: identity assertion (SEP-990, beta), provider-neutral role checks, insufficient-scope challenges that name the missing scopes, and client-credentials auth.
• Infrastructure hooks: server-level cache hints, and Mcp-Method/Mcp-Name routing headers so gateways can route without parsing JSON-RPC.

The framework grew alongside the protocol: dependency injection can bind a dependency to arguments of the call it serves (Depends(get_account, user_id=CallArgument("owner"))) while keeping it out of the tool schema, and ClientGroup manages one client per server with collision-checked namespacing — each member negotiating its own protocol version.

The beta period motivated a bunch of correctness work. Most of it was auth: hardened OAuth consent flows, issuer validation, and JWT verification, plus proxies that strip cookies and connection-owned headers at trust boundaries. The rest was durability and compatibility — encrypted task snapshots, serialized event-store writes, response caching handling empty results, errors, and versioned components, and dozens of smaller fixes from CodeMode to Python 3.14 compat.

Breaking changes: server-initiated sampling and roots are removed (no live connection exists to call back into mid-request), ctx.elicit() is old-protocol-only, FastMCP 3's deprecated APIs are gone, MCP model fields are snake_case (with a warning compatibility bridge for the old names), and background tasks moved to fastmcp-tasks. Passing a bare string like Client("server.py") to run local code is deprecated in favor of Path, for removal in FastMCP 5.

The upgrade guide covers every change and includes a copyable prompt for auditing an application with a coding agent.

Happy (context) engineering!

What's Changed

New Features 🎉

• Migrate to MCP Python SDK v2 by @jlowin in #4437
• Teach fastmcp.Client the modern protocol: mode negotiation, MRTR driver, response cache by @jlowin in #4450
• Forward-port Hugging Face auth provider by @jlowin in #4475
• Add server-side identity assertion (SEP-990 ID-JAG) by @jlowin in #4483
• Add guard-mode multi-round-trip tools (SEP-2322) by @jlowin in #4544
• Add FastMCP-native server extension API (SEP-2133) by @jlowin in #4602
• Add stateless session state (UserSession / SessionId) by @jlowin in #4604
• Add background tasks via the io.modelcontextprotocol/tasks extension (SEP-2663) by @jlowin in #4603

Breaking Changes ⚠️

• Emit one SERVER span per request and adopt spec-correct error codes by @jlowin in #4445
• Remove 3.x deprecated module shims and dead parameters by @jlowin in #4447
• Remove 3.0-deprecated FastMCP server methods by @jlowin in #4451
• Remove 3.x deprecated parameters and object-mode decorators by @jlowin in #4453
• Migrate to MCP SDK v2.0.0b2 (httpx2) by @jlowin in #4503
• Fix typos by @szepeviktor in #4498
• Stop proxies from validating backend results or mutating shared transports by @jlowin in #4552
• Surface resource, prompt, and proxy errors on the modern protocol by @jlowin in #4579
• Negotiate the best mutual protocol era by default by @jlowin in #4572
• Remove server-initiated sampling and roots from the server API by @jlowin in #4648
• Remove 3.x-era compatibility shims by @jlowin in #4661

Enhancements ✨

• Deprecate ctx.sample and add clear errors for push features on 2026 connections by @jlowin in #4448
• Add server-level cache hints (SEP-2549) by @jlowin in #4464
• Add KeyValueResponseCacheStore for distributed client response caching by @jlowin in #4479
• Test lifespan fires once per process over HTTP by @jlowin in #4480
• Add telemetry off-switch and mcp.protocol.version span attribute by @jlowin in #4481
• Trace client task management requests by @jlowin in #4525
• Stabilize upgraded ty checks by @jlowin in #4526
• Improve DescopeProvider scope discovery and well-known URL support by @gaokevin1 in #4489
• Add examples/ to the ty static-analysis gate by @jlowin in #4466
• Expose telemetry attributes on span start by @zzstoatzz in #4487
• Fix-issue-4284 : Add Auth0MCPProvider for Auth0 Auth for MCP by @vijaydeepsinha in #4411
• Run FastMCP middleware for every inbound message by @jlowin in #4553
• Add 'prs welcome' label to waive the PR assignment gate by @jlowin in #4557
• Rename martian workflows to marvin by @jlowin in #4558
• Bump pinned Claude models to current versions by @jlowin in #4561
• Make the unit suite fast: in-process HTTP tests, no real sleeps, parallel Windows CI by @jlowin in #4554
• Mirror the frontend's protocol era on a proxy's backend connection by @jlowin in #4573
• Drop forked client protocol helpers in favor of the SDK's by @jlowin in #4574
• Bring the v4 developer notes up to date with what shipped by @jlowin in #4581
• Trim fastmcp.types to FastMCP-unique types by @jlowin in #4584
• Let a server answer argument-completion requests by @jlowin in #4582
• Add machine-to-machine client authentication by @jlowin in #4583
• Expose era-neutral client server metadata by @zzstoatzz in #4599
• Support routable transport headers for gateways (SEP-2243) by @jlowin in #4622
• Emit scope step-up challenges for incremental authorization (SEP-2350) by @jlowin in #4623
• Honor OAuth application_type in DCR (SEP-837) by @jlowin in #4621
• Drop stale label-noting instructions from CLAUDE.md by @jlowin in #4654
• Add require_roles auth check by @jlowin in #4656
• Add valid_scopes parameter to OIDC proxy valid scopes by @Educg550 in #4660
• feat: Add telemetry interop mode for FastMCP by @strawgate in #4046
• Note that review comment threads should get an acknowledgement by @jlowin in #4678
• Soften the review-comment reply guidance by @jlowin in #4683
• Resolve review threads on fix, reply on decline by @jlowin in #4685
• Move to the stable MCP Python SDK 2.0.0 by @jlowin in #4655
• Add comprehensive Codex code review rules by @jlowin in #4710
• Give parallel Windows CI more timeout headroom by @zzstoatzz in #4680
• add language dropdown to docs sidebar by @znicholasbrown in #4716
• R...

v4.0.0b5: Group Effourt

FastMCP 4 beta 5 introduces ClientGroup — one managed client per server, each negotiating its own protocol era independently, with collision-checked tool namespacing and call routing and no proxy in the middle. It also aligns middleware response limits with output schemas.

What's Changed

Enhancements ✨

• Remove obsolete Docket memory-server reset fixtures by @TyceHerrman in #4912
• add independent client groups by @zzstoatzz in #4904

Fixes 🐞

• fix(ci): satisfy latest ty control-flow checks by @zzstoatzz in #4928
• fix(middleware): align response limits with output schemas by @zzstoatzz in #4931

Docs 📚

• docs: fix beta 4 changelog MDX by @zzstoatzz in #4916
• docs: prepare FastMCP 4 beta 5 by @zzstoatzz in #4934

New Contributors

• @TyceHerrman made their first contribution in #4912

Full Changelog: v4.0.0b4...v4.0.0b5

v4.0.0b4: Calm Befour the Storm

FastMCP 4 beta 4 improves modern multi-server clients and adds Prefect Horizon account commands. It also tightens proxy and CIMD security boundaries and fixes Unicode search and MCP inspect output.

What's Changed

Enhancements ✨

• Add Prefect Horizon account commands by @parkedwards in #4786
• Cap anthropic dependency to <1 by @craigie-ant in #4864

Security 🔒

• Scope Marvin App token to each job's declared permissions by @zzstoatzz in #4834
• Exclude Cookie from forwarded HTTP headers by @zzstoatzz in #4843
• Bump cryptography to 50.0.0 in the testing_demo example by @zzstoatzz in #4844
• Bound CIMD cache growth by @jlowin in #4852

Fixes 🐞

• Fix instructions in MCP inspect output by @zzstoatzz in #4873
• fix: support Unicode tokens in BM25 search by @zzstoatzz in #4889
• fix: support modern protocol in multi-server clients by @zzstoatzz in #4893

Docs 📚

• docs: fix idempotent tool hint wording by @Theater-ahyeon in #4875
• docs: prepare FastMCP 4 beta 4 by @zzstoatzz in #4914

Other Changes 🦾

• chore(deps): Update j178/prek-action action to v3 by @prefect-renovate[bot] in #4808
• chore(deps): Update dependency node to v24 by @prefect-renovate[bot] in #4807
• chore(deps): Update astral-sh/setup-uv action to v9 by @prefect-renovate[bot] in #4806
• Fix proxy forwarding of MCP transport headers by @jakekaplan in #4853
• Add FastMCP security report review skill by @zzstoatzz in #4859

New Contributors

• @prefect-renovate[bot] made their first contribution in #4808
• @craigie-ant made their first contribution in #4864
• @Theater-ahyeon made their first contribution in #4875

Full Changelog: v4.0.0b3...v4.0.0b4

v4.0.0b3: Fast Fourward

docs: add FastMCP 4 beta 3 release entries (#4841)

v3.4.7: Know Your Audience

FastMCP 3.4.7 restores CIMD private_key_jwt authentication for OAuthProxy deployments at a bare origin. Client assertions are now validated against the exact token endpoint advertised in authorization server metadata, eliminating the doubled-slash audience mismatch.

What's Changed

Security 🔒

• Backport CIMD assertion audience fix to v3 by @jlowin in #4799

Docs 📚

• Docs: add v3.4.7 changelog entries by @jlowin in #4810

Full Changelog: v3.4.6...v3.4.7

v4.0.0b2: Four the Better

Serialize the event store's stream list read-modify-write (#4758)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>

v3.4.6: Trust, but Proxy

FastMCP 3.4.6 backports trusted-proxy support for SSRF-protected OAuth metadata and JWKS fetches. Deployments can now route these requests through a mandated corporate proxy while preserving custom CA certificates; FastMCP refuses the fetch when no proxy is configured instead of risking an unprotected direct request.

What's Changed

Fixes 🐞

• Backport #4412 to 3.x: support trusted SSRF proxies by @jlowin in #4755

Docs 📚

• Docs: add v3.4.6 changelog entries by @jlowin in #4761

Full Changelog: v3.4.5...v3.4.6