jlowin/fastmcp v2.14.0 on GitHub

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 AsyncKeyValue support
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 #2513
[2.14] SEP-1686 tasks by @chrisguidry in #2378

Enhancements 🔧

Expose InitializeResult to middleware by @jlowin in #2516
[2.14] Update for MCP SDK auth changes by @chrisguidry in #2507
Validate tool names at registration time (SEP-986) by @jlowin in #2540
Deflake GitHub MCP remote integration tests by @chrisguidry in #2543
Add SEP-1034 default values support for elicitation by @jlowin in #2545
Improve rate limit detection for integration tests by @chrisguidry in #2550
Reduce Marvin Test Failure noise by @strawgate in #2553
[SEP-1686] Raise ValueError when sync functions have task=True by @jlowin in #2554
refactor: move task attribute to function-based variants only [SEP-1686] by @jlowin in #2560
Fix type errors for ty 0.0.1-alpha.31 upgrade by @jlowin in #2561
Add regression tests for functools.wraps + Context (#2524) by @jlowin in #2566
Update VersionBadge to use Mintlify native Badge component by @jlowin in #2571
Add TaskConfig for SEP-1686 execution modes by @jlowin in #2570
Add execution field to base Tool class by @chrisguidry in #2576
SEP-1699: Add SSE polling support with EventStore by @jlowin in #2564
SEP-1330 enum schema support by @jlowin in #2549
Expose get_session_id callback by @mathewjhan in #2486
Remove TaskConfig and client from root exports by @jlowin in #2580
Remove overly restrictive MIME type validation from Resource by @jlowin in #2585
feat: handle error from the initialize middleware by @tonyxwz in #2531
Remove tests/test_examples.py by @jlowin in #2593

Fixes 🐞

Fix RFC 8414 path-aware authorization server metadata discovery by @jlowin in #2533
Make fastapi.cli a runnable package by @paulo-raca in #2532
Move TokenHandler to OAuthProvider for consistent OAuth error codes by @jlowin in #2538
Update FastMCP server documentation link by @sskim91 in #2529
Fix: Include signature modification in create_function_without_params by @AidanAllchin in #2563
add client kwargs to proxy clients and meta to proxy tool calls by @cegersdoerfer in #2520
Prefix Docket function names to avoid collisions in multi-mount setups by @chrisguidry in #2575
Fix OAuth client to preserve full URL path for metadata discovery by @jlowin in #2577
Do not run windows tests in parallel by @jlowin in #2579
Fix proxy tool result meta attribute forwarding by @dherrman in #2526
Fix nested server mount routing for 3+ levels deep by @jlowin in #2586
Add smart fallback for missing access token expiry by @jlowin in #2587
fix: preserve exception propagation through transport cleanup by @jlowin in #2591

Breaking Changes 🛫

Remove enable_docket setting; Docket is now always on by @chrisguidry in #2558
Forbid task execution through proxies, add mount/proxy task tests by @chrisguidry in #2574
Remove enable_tasks setting, enable task protocol by default by @chrisguidry in #2578
Remove deprecated from fastmcp.settings import settings by @jlowin in #2581
Remove deprecated mount/import argument order and separator params by @jlowin in #2582
2.14 deprecation removals by @jlowin in #2329
Note that #2329 includes the following PRs:
- Remove deprecated FASTMCP_SERVER_ environment variable prefix by @jlowin in #2330
- Remove deprecated Context.get_http_request method by @jlowin in #2332
- Remove fastmcp.Image top-level import (deprecated 2.8.1) by @jlowin in #2334
- Remove deprecated client parameter from FastMCPProxy by @jlowin in #2333
- Remove deprecated run_streamable_http_async method by @jlowin in #2338
- Remove deprecated sse_app method by @jlowin in #2337
- Remove deprecated run_sse_async method by @jlowin in #2335
- Remove deprecated streamable_http_app method by @jlowin in #2336
- Remove deprecated dependencies parameter (fixes #2177) by @jlowin in #2340
- Remove output_schema=False support (deprecated 2.11.4) by @jlowin in #2339
- Remove deprecated BearerAuthProvider module by @jlowin in #2341
- Remove resource_prefix_format="protocol" support (deprecated 2.4.0) by @jlowin in #2342
- Remove from_client classmethod (deprecated 2.8.0) by @jlowin in #2343
- Remove add_resource_fn method (deprecated 2.7.0) by @jlowin in #2345

Docs 📚

Add OCI integration to docs navigation by @jlowin in #2515
Add supabase docs by @jlowin in #2030
Add v2.14.0 upgrade guide by @jlowin in #2565
docs: document stateless_http for horizontal scaling by @alexjacobs08 in #2547
Rewrite background tasks documentation by @jlowin in #2567
[Draft] Add documentation for read-only tool patterns by @strawgate in #2536

New Contributors

@paulo-raca made their first contribution in #2532
@sskim91 made their first contribution in #2529
@AidanAllchin made their first contribution in #2563
@alexjacobs08 made their first contribution in #2547
@mathewjhan made their first contribution in #2486
@dherrman made their first contribution in #2526
@tonyxwz made their first contribution in #2531

Full Changelog: v2.13.2...v2.14.0

jlowin/fastmcp v2.14.0 v2.14.0: Task and You Shall Receive on GitHub