v2.14.0: Task and You Shall Receive
FastMCP 2.14 begins adopting the MCP 2025-11-25 specification, headlined by protocol-native background tasks that let long-running operations report progress without blocking clients. This release also graduates the OpenAPI parser to standard, adds first-class support for several new spec features, and removes deprecated APIs accumulated across the 2.x series.
Background Tasks (SEP-1686)
Long-running operations (like tool calls) normally block MCP clients until they complete. The new MCP background task protocol (SEP-1686) lets clients start operations, track progress, and retrieve results without blocking. For FastMCP users, taking advantage of this new functionality is as easy as adding task=True to any async decorator. Under the hood, it's powered by Docket, the enterprise task scheduler at the heart of Prefect Cloud that handles millions of concurrent tasks every day.
from fastmcp import FastMCP
from fastmcp.dependencies import Progress
mcp = FastMCP("MyServer")
@mcp.tool(task=True)
async def train_model(dataset: str, progress: Progress = Progress()) -> str:
await progress.set_total(100)
for epoch in range(100):
# ... training work ...
await progress.increment()
return "Model trained successfully"
Clients that call this tool in task-augmented mode (for FastMCP clients, that merely means another task=True!) receive a task ID immediately, poll for progress updates, and fetch results when ready. Background tasks work out-of-the-box with an in-memory backend, and users can optionally provide a Redis URL for persistence, horizontal scaling, and single-digit millisecond task pickup latency. When using Redis, users can also add additional Docket workers to scale out their task processing.
Read the docs here!
OpenAPI Parser Promotion
The experimental OpenAPI parser graduates to standard. The new architecture delivers improved performance through single-pass schema processing and cleaner internal abstractions. Existing code works unchanged; users of the experimental module should update their imports.
MCP 2025-11-25 Spec Support
This release begins adopting the MCP 2025-11-25 specification. Beyond the core SDK updates, FastMCP adds first-class developer experiences for:
- SEP-1686: Background tasks with progress tracking
- SEP-1699: SSE polling and event resumability, with full
AsyncKeyValuesupport - SEP-1330: Multi-select enum elicitation schemas
- SEP-1034: Default values for elicitation schemas
- SEP-986: Tool name validation at registration time
As the MCP SDK continues to adopt more of the specification, FastMCP will add corresponding high-level APIs.
Breaking Changes & Cleanup
This release removes deprecated APIs accumulated across the 2.x series: BearerAuthProvider, Context.get_http_request(), the dependencies parameter, legacy resource prefix formats, and several deprecated methods. The upgrade guide provides migration paths for each.
What's Changed
New Features 🎉
- Switch to new OpenAPI parser as default by @jlowin in https://github.com/jlowin/fastmcp/pull/2513
- [2.14] SEP-1686 tasks by @chrisguidry in https://github.com/jlowin/fastmcp/pull/2378
Enhancements 🔧
- Expose InitializeResult to middleware by @jlowin in https://github.com/jlowin/fastmcp/pull/2516
- [2.14] Update for MCP SDK auth changes by @chrisguidry in https://github.com/jlowin/fastmcp/pull/2507
- Validate tool names at registration time (SEP-986) by @jlowin in https://github.com/jlowin/fastmcp/pull/2540
- Deflake GitHub MCP remote integration tests by @chrisguidry in https://github.com/jlowin/fastmcp/pull/2543
- Add SEP-1034 default values support for elicitation by @jlowin in https://github.com/jlowin/fastmcp/pull/2545
- Improve rate limit detection for integration tests by @chrisguidry in https://github.com/jlowin/fastmcp/pull/2550
- Reduce Marvin Test Failure noise by @strawgate in https://github.com/jlowin/fastmcp/pull/2553
- [SEP-1686] Raise ValueError when sync functions have task=True by @jlowin in https://github.com/jlowin/fastmcp/pull/2554
- refactor: move task attribute to function-based variants only [SEP-1686] by @jlowin in https://github.com/jlowin/fastmcp/pull/2560
- Fix type errors for ty 0.0.1-alpha.31 upgrade by @jlowin in https://github.com/jlowin/fastmcp/pull/2561
- Add regression tests for functools.wraps + Context (#2524) by @jlowin in https://github.com/jlowin/fastmcp/pull/2566
- Update VersionBadge to use Mintlify native Badge component by @jlowin in https://github.com/jlowin/fastmcp/pull/2571
- Add TaskConfig for SEP-1686 execution modes by @jlowin in https://github.com/jlowin/fastmcp/pull/2570
- Add execution field to base Tool class by @chrisguidry in https://github.com/jlowin/fastmcp/pull/2576
- SEP-1699: Add SSE polling support with EventStore by @jlowin in https://github.com/jlowin/fastmcp/pull/2564
- SEP-1330 enum schema support by @jlowin in https://github.com/jlowin/fastmcp/pull/2549
- Expose get_session_id callback by @mathewjhan in https://github.com/jlowin/fastmcp/pull/2486
- Remove TaskConfig and client from root exports by @jlowin in https://github.com/jlowin/fastmcp/pull/2580
- Remove overly restrictive MIME type validation from Resource by @jlowin in https://github.com/jlowin/fastmcp/pull/2585
- feat: handle error from the initialize middleware by @tonyxwz in https://github.com/jlowin/fastmcp/pull/2531
- Remove tests/test_examples.py by @jlowin in https://github.com/jlowin/fastmcp/pull/2593
Fixes 🐞
- Fix RFC 8414 path-aware authorization server metadata discovery by @jlowin in https://github.com/jlowin/fastmcp/pull/2533
- Make fastapi.cli a runnable package by @paulo-raca in https://github.com/jlowin/fastmcp/pull/2532
- Move TokenHandler to OAuthProvider for consistent OAuth error codes by @jlowin in https://github.com/jlowin/fastmcp/pull/2538
- Update FastMCP server documentation link by @sskim91 in https://github.com/jlowin/fastmcp/pull/2529
- Fix: Include signature modification in create_function_without_params by @AidanAllchin in https://github.com/jlowin/fastmcp/pull/2563
- add client kwargs to proxy clients and meta to proxy tool calls by @cegersdoerfer in https://github.com/jlowin/fastmcp/pull/2520
- Prefix Docket function names to avoid collisions in multi-mount setups by @chrisguidry in https://github.com/jlowin/fastmcp/pull/2575
- Fix OAuth client to preserve full URL path for metadata discovery by @jlowin in https://github.com/jlowin/fastmcp/pull/2577
- Do not run windows tests in parallel by @jlowin in https://github.com/jlowin/fastmcp/pull/2579
- Fix proxy tool result meta attribute forwarding by @dherrman in https://github.com/jlowin/fastmcp/pull/2526
- Fix nested server mount routing for 3+ levels deep by @jlowin in https://github.com/jlowin/fastmcp/pull/2586
- Add smart fallback for missing access token expiry by @jlowin in https://github.com/jlowin/fastmcp/pull/2587
- fix: preserve exception propagation through transport cleanup by @jlowin in https://github.com/jlowin/fastmcp/pull/2591
Breaking Changes 🛫
- Remove enable_docket setting; Docket is now always on by @chrisguidry in https://github.com/jlowin/fastmcp/pull/2558
- Forbid task execution through proxies, add mount/proxy task tests by @chrisguidry in https://github.com/jlowin/fastmcp/pull/2574
- Remove enable_tasks setting, enable task protocol by default by @chrisguidry in https://github.com/jlowin/fastmcp/pull/2578
- Remove deprecated
from fastmcp.settings import settingsby @jlowin in https://github.com/jlowin/fastmcp/pull/2581 - Remove deprecated mount/import argument order and separator params by @jlowin in https://github.com/jlowin/fastmcp/pull/2582
- 2.14 deprecation removals by @jlowin in https://github.com/jlowin/fastmcp/pull/2329
Note that #2329 includes the following PRs:
- Remove deprecated FASTMCP_SERVER_ environment variable prefix by @jlowin in https://github.com/jlowin/fastmcp/pull/2330
- Remove deprecated Context.get_http_request method by @jlowin in https://github.com/jlowin/fastmcp/pull/2332
- Remove fastmcp.Image top-level import (deprecated 2.8.1) by @jlowin in https://github.com/jlowin/fastmcp/pull/2334
- Remove deprecated client parameter from FastMCPProxy by @jlowin in https://github.com/jlowin/fastmcp/pull/2333
- Remove deprecated run_streamable_http_async method by @jlowin in https://github.com/jlowin/fastmcp/pull/2338
- Remove deprecated sse_app method by @jlowin in https://github.com/jlowin/fastmcp/pull/2337
- Remove deprecated run_sse_async method by @jlowin in https://github.com/jlowin/fastmcp/pull/2335
- Remove deprecated streamable_http_app method by @jlowin in https://github.com/jlowin/fastmcp/pull/2336
- Remove deprecated dependencies parameter (fixes #2177) by @jlowin in https://github.com/jlowin/fastmcp/pull/2340
- Remove output_schema=False support (deprecated 2.11.4) by @jlowin in https://github.com/jlowin/fastmcp/pull/2339
- Remove deprecated BearerAuthProvider module by @jlowin in https://github.com/jlowin/fastmcp/pull/2341
- Remove resource_prefix_format="protocol" support (deprecated 2.4.0) by @jlowin in https://github.com/jlowin/fastmcp/pull/2342
- Remove from_client classmethod (deprecated 2.8.0) by @jlowin in https://github.com/jlowin/fastmcp/pull/2343
- Remove add_resource_fn method (deprecated 2.7.0) by @jlowin in https://github.com/jlowin/fastmcp/pull/2345
Docs 📚
- Add OCI integration to docs navigation by @jlowin in https://github.com/jlowin/fastmcp/pull/2515
- Add supabase docs by @jlowin in https://github.com/jlowin/fastmcp/pull/2030
- Add v2.14.0 upgrade guide by @jlowin in https://github.com/jlowin/fastmcp/pull/2565
- docs: document stateless_http for horizontal scaling by @alexjacobs08 in https://github.com/jlowin/fastmcp/pull/2547
- Rewrite background tasks documentation by @jlowin in https://github.com/jlowin/fastmcp/pull/2567
- [Draft] Add documentation for read-only tool patterns by @strawgate in https://github.com/jlowin/fastmcp/pull/2536
New Contributors
- @paulo-raca made their first contribution in https://github.com/jlowin/fastmcp/pull/2532
- @sskim91 made their first contribution in https://github.com/jlowin/fastmcp/pull/2529
- @AidanAllchin made their first contribution in https://github.com/jlowin/fastmcp/pull/2563
- @alexjacobs08 made their first contribution in https://github.com/jlowin/fastmcp/pull/2547
- @mathewjhan made their first contribution in https://github.com/jlowin/fastmcp/pull/2486
- @dherrman made their first contribution in https://github.com/jlowin/fastmcp/pull/2526
- @tonyxwz made their first contribution in https://github.com/jlowin/fastmcp/pull/2531
Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.13.2...v2.14.0