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

v4.0.0b1: Fourgone Conclusion

FastMCP 4 makes stateful MCP applications work on the sessionless 2026-07-28 protocol while one deployment continues serving handshake-era clients. Tools can ask follow-up questions across requests, preserve authenticated user state, and move long-running work into background tasks without sticky sessions or a continuously connected client.

The engine underneath changed completely. MCP Python SDK v2 rewrote the protocol layer end to end — protocol types moved into a standalone mcp_types package (still importable as mcp.types), model fields use snake_case in Python, and the server request-handling model was replaced. FastMCP absorbs nearly all of it, so most FastMCP 3 servers upgrade untouched.

🌐 Every protocol era — modern and handshake-era clients are served simultaneously, negotiated per connection. Modern requests can be handled by any replica behind an ordinary load balancer.

💬 Interactive tools — tools ask follow-up questions across complete request-response rounds. Shared request-state keys let any replica resume the next round after load balancing or a worker restart.

💾 State without a session — UserSession and SessionId give tools explicit per-user state on a protocol that deliberately has none (SEP-2567), stored server-side and keyed to the authenticated user.

⏳ Background tasks — the io.modelcontextprotocol/tasks extension (SEP-2663), shipped in the new fastmcp-tasks package on the same Docket engine FastMCP 3 used. @mcp.tool(task=True) is still the whole authoring surface.

🧩 Server extensions — add_extension() turns capability-negotiated protocol features (SEP-2133) into a supported plugin surface instead of surgery on core.

🔐 Enterprise auth — complete server-side identity assertion (SEP-990), plus require_roles, incremental-authorization step-up challenges (SEP-2350), DCR application_type (SEP-837), and routable transport headers for gateways (SEP-2243).

⌨️ Argument completion — a @mcp.completion handler answers autocomplete for prompt arguments and resource-template parameters, and can narrow suggestions using the arguments already supplied.

Breaking changes. Server-initiated sampling and roots are removed from the server API: both pushed a request down a live connection, which the sessionless protocol no longer has, and a method that only works against old clients is a trap. Elicitation continues in a request-shaped form, and generation belongs in your server — call an LLM directly. The 3.x-era compatibility shims are also gone. The upgrade guide walks through every change.

Install the beta by pinning it explicitly:

uv add "fastmcp==4.0.0b1"

This is a beta released for testing ahead of 4.0. Pin an exact version and expect sharp edges.

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

Security 🔒

• Drive the FastMCP lifespan through the SDK session manager by @jlowin in #4446
• Route skill file access through SDK path-security primitives by @jlowin in #4449
• Screen templated resource parameters for path traversal by default by @jlowin in #4482
• [codex] Add OAuthProxy RFC 9207 issuer responses by @jlowin in #4438
• Apply app visibility where no host can by @jlowin in #4692

Fixes 🐞

• Capture SharedContext for task-enabled Docket servers by @jlowin in #4443
• Fix stale mcp.types imports in examples by @jlowin in https://github...

v3.4.5: Key Change

FastMCP 3.4.5 collects five fixes for the 3.x line. The one that prompted it: a single Ed25519 key in a JWKS — which Rauthy, Ory Hydra, and some Keycloak configurations publish by default — made JWTVerifier reject every token, including ones correctly signed by supported keys in the same set.

What's Changed

Fixes 🐞

• Backport #4517 to release/3.x: skip unsupported JWKS keys (#4515) by @kakiii in #4631
• Backport #4469 to release/3.x: fix Azure scope fallback by @jlowin in #4662
• Backport #4523 to release/3.x: serialize deep object query parameters by @jlowin in #4664
• Backport #4564 to release/3.x: make transformed tool required order deterministic by @jlowin in #4665
• Backport #4492 to release/3.x: don't mutate the caller's schema in compress_schema by @jlowin in #4663

Docs 📚

• Docs: add v3.4.5 changelog entries by @jlowin in #4673

New Contributors

• @kakiii made their first contribution in #4631

Full Changelog: v3.4.4...v3.4.5

v4.0.0a2: Back and Fourth

chore: Update SDK documentation (#4615)

v4.0.0a1: Fourst Contact

Document v3->v4 removals and add upgrade-reality tests (#4585)

* Document v3->v4 removals and add upgrade-reality tests

* Check canonical imports in a clean subprocess to avoid suite import pollution

* Address review: import_server semantics note, pin traversal error, drop redundant import

* Address review round 2: real screening test, Depends factory, remove_tool/create_proxy notes

* Validate canonical imports in-process; fix lifespan/timeout/error-code/starlette doc notes

* Reconcile with fastmcp.types trim: import protocol types from mcp_types

* Record v4 release codename arc in dev notes

v3.4.4: Host in Translation

FastMCP 3.4.4 restores HTTP deployment compatibility after the 3.4.3 Host/Origin guard changed default behavior for existing ASGI, serverless, and reverse-proxy deployments. The guard implementation remains available for deployments that opt in with explicit trusted hosts and origins, while 3.x returns to accepting traffic that worked before the patch. This release also adds Hugging Face OAuth provider support, with docs and examples for public and private apps, PKCE, Dynamic Client Registration, and CIMD.

What's Changed

Enhancements ✨

• Hugging Face Auth Integration by @evalstate in #4385

Fixes 🐞

• Relax host origin guard defaults by @jlowin in #4439
• Restore HTTP host guard compatibility by @jlowin in #4472

Docs 📚

• Docs: add v3.4.4 changelog entries by @jlowin in #4473

New Contributors

• @evalstate made their first contribution in #4385

Full Changelog: v3.4.3...v3.4.4

v3.4.3: The Fast and the Secure-ious

FastMCP 3.4.3 closes out a month of SSRF and OAuth hardening: NAT64, 6to4, Teredo, and ISATAP transition addresses can no longer smuggle private IPv4 targets past the SSRF allow-list, Streamable HTTP now validates Host and Origin before session handling to block DNS rebinding against localhost-bound servers, and OAuth redirect validation rejects unsafe schemes and unregistered DCR redirect URIs. Alongside the security work, this release also fixes proxy session teardown races, discriminator-tag handling in JSON schema conversion, and several smaller reliability issues.

What's Changed

Enhancements ✨

• Dedupe discriminator-required helper across schema converters by @jlowin in #4362
• Add real Monty sandbox e2e coverage for CodeMode call_tool by @AlexlaGuardia in #4274
• Switch prettier hook to rbubley/mirrors-prettier by @jlowin in #4366
• feat(remote): add --verify flag for TLS certificate verification by @jlowin in #4369

Security 🔒

• fix(deps): clear Dependabot security alerts via lockfile bumps by @jlowin in #4393
• Clarify resource path parameter safety by @jlowin in #4398
• Fix dev apps launch escaping by @jlowin in #4399
• Block NAT64 SSRF bypass by @jlowin in #4400
• [codex] Fix event store replay isolation by @jlowin in #4402
• Fix DCR redirect URI validation by @jlowin in #4408
• Protect streamable HTTP from DNS rebinding by @jlowin in #4405
• Block unsafe OAuth redirect schemes by @jlowin in #4419
• Block IPv6 transition SSRF bypasses by @jlowin in #4426

Fixes 🐞

• fix: caching middleware TypeError on cache miss due to mismatched call_next parameter by @gmenziesint in #4301
• Fix: async rate limiting middleware get_client_id callbacks by @Chotom in #4319
• Recognize all GitHub issue-link forms in require-issue-link workflow by @jlowin in #4359
• fix: preserve required discriminator tags by @he-yufeng in #4297
• fix(proxy): shield stateful proxy disconnect during session teardown by @jlowin in #4363
• fix(fs): isolate same-named package imports across providers by @jlowin in #4361
• fix: StatefulProxyClient.clear() no longer causes KeyError on session teardown by @tcconnally in #4328
• fix: guard recursive refs in json_schema_to_type by @Epochex in #4312
• Forward IdP auth errors to MCP client instead of showing HTML error page by @bobbyjames839 in #4293
• fix(resources): round-trip path values with reserved characters in URI templates by @jlowin in #4368
• fix: bracket IPv6 hosts in server startup log URL by @jlowin in #4372
• fix: bound default OIDC discovery timeout and expose it on provider wrappers by @jlowin in #4374
• fix: validate task tool arguments against declared types by @jlowin in #4373
• fix(tools): honor serialize_by_alias in tool result serialization by @jlowin in #4391
• Fix/cimd flow issue by @twjackysu in #4206
• Reject empty env var keys by @CodingFeng101 in #4410
• fix: correct replace_type docstring parameter descriptions by @hiSandog in #4375
• Fix ty 0.0.55 diagnostics and prefab-ui protocol version drift by @jlowin in #4428
• [codex] Fix OpenAPI resource template requests by @jlowin in #4407

Docs 📚

• fix: RST docstrings in fastmcp.types render raw on gofastmcp.com by @jlowin in #4367
• docs: fix 5 broken internal links (auth & providers pages) by @Michael-WhiteCapData in #4344
• docs: add audit/event-record recipe for tool-call middleware by @AlexlaGuardia in #4345

Dependencies 📦

• chore(deps): bump actions/checkout from 6 to 7 by @dependabot[bot] in #4343
• chore(deps): bump joserfc from 1.6.5 to 1.6.7 in the uv group across 1 directory by @dependabot[bot] in #4394
• chore(deps): bump joserfc from 1.6.7 to 1.6.8 in the uv group across 1 directory by @dependabot[bot] in #4429

Other Changes 🦾

• Raise fastmcp.ValidationError for invalid tool arguments by @jlowin in #4392
• Fix versioned auth middleware checks by @jlowin in #4401
• Docs: add v3.4.2 and v3.4.3 changelog entries by @jlowin in #4430

New Contributors

• @gmenziesint made their first contribution in #4301
• @Chotom made their first contribution in #4319
• @he-yufeng made their first contribution in #4297
• @AlexlaGuardia made their first contribution in #4274
• @tcconnally made their first contribution in #4328
• @Epochex made their first contribution in #4312
• @Michael-WhiteCapData made their first contribution in #4344
• @bobbyjames839 made their first contribution in #4293
• @twjackysu made their first contribution in #4206
• @CodingFeng101 made their first contribution in #4410
• @hiSandog made their first contribution in #4375

Full Changelog: v3.4.2...v3.4.3