New
v3.0.0: Three at Last
FastMCP 3.0 is stable. Two betas, two release candidates, 21 new contributors, and more than 100,000 pre-release installs later β the architecture held up, the upgrade path was smooth, and we're shipping it.
The surface API is largely unchanged β @mcp.tool() still works exactly as before. What changed is everything underneath: a provider/transform architecture that makes FastMCP extensible, observable, and composable in ways v2 couldn't support. If we did our jobs right, you'll barely notice the redesign. You'll just notice that more is possible.
This is also the release where FastMCP moves from jlowin/fastmcp to PrefectHQ/fastmcp. GitHub forwards all links, PyPI is the same, imports are the same. A major version felt like the right moment to make it official.
Build servers from anything
π Components no longer have to live in one file with one server. FileSystemProvider discovers tools from directories with hot-reload. OpenAPIProvider wraps REST APIs. ProxyProvider proxies remote MCP servers. SkillsProvider delivers agent skills as resources. Write your own provider for whatever source makes sense. Compose multiple providers into one server, share one across many, or chain them with transforms that rename, namespace, filter, version, and secure components as they flow to clients. ResourcesAsTools and PromptsAsTools expose non-tool components to tool-only clients.
Ship to production
π Component versioning: serve @tool(version="2.0") alongside older versions from one codebase. Granular authorization on individual components with async auth checks, server-wide policies via AuthMiddleware, and scope-based access control. OAuth gets CIMD, Static Client Registration, Azure OBO via dependency injection, JWT audience validation, and confused-deputy protections. OpenTelemetry tracing with MCP semantic conventions. Response size limiting. Background tasks with distributed Redis notification and ctx.elicit() relay. Security fixes include dropping diskcache (CVE-2025-69872) and upgrading python-multipart and protobuf for additional CVEs.
Adapt per session
πΎ Session state persists across requests via ctx.set_state() / ctx.get_state(). ctx.enable_components() and ctx.disable_components() let servers adapt dynamically per client β show admin tools after authentication, progressively reveal capabilities, or scope access by role.
Develop faster
β‘ --reload auto-restarts on file changes. Standalone decorators return the original function, so decorated tools stay callable in tests and non-MCP contexts. Sync functions auto-dispatch to a threadpool. Tool timeouts, MCP-compliant pagination, composable lifespans, PingMiddleware for keepalive, and concurrent tool execution when the LLM returns multiple calls in one response.
Use FastMCP as a CLI
π₯οΈ fastmcp list and fastmcp call query and invoke tools on any server from a terminal. fastmcp discover scans your editor configs (Claude Desktop, Cursor, Goose, Gemini CLI) and finds configured servers by name. fastmcp generate-cli writes a standalone typed CLI where every tool is a subcommand. fastmcp install registers your server with Claude Desktop, Cursor, or Goose in one command.
Build apps (3.1 preview)
π± Spec-level support for MCP Apps is in: ui:// resource scheme, typed UI metadata via AppConfig, extension negotiation, and runtime detection. The full Apps experience lands in 3.1.
If you hit 3.0 because you didn't pin your dependencies and something breaks β the upgrade guides will get you sorted. We minimized breaking changes, but a major version is a major version.
pip install fastmcp -U
π Documentation π Upgrade from FastMCP v2 π Upgrade from MCP Python SDK π° What's New in FastMCP 3.0
What's Changed
New Features π
- Refactor resource behavior and add meta support by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2611
- Refactor prompt behavior and add meta support by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2610
- feat: Provider abstraction for dynamic MCP components by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2622
- Unify component storage in LocalProvider by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2680
- Introduce ResourceResult as canonical resource return type by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2734
- Introduce Message and PromptResult as canonical prompt types by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2738
- Add --reload flag for auto-restart on file changes by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2816
- Add FileSystemProvider for filesystem-based component discovery by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2823
- Add standalone decorators and eliminate fastmcp.fs module by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2832
- Add authorization checks to components and servers by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2855
- Decorators return functions instead of component objects by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2856
- Add transform system for modifying components in provider chains by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2836
- Add OpenTelemetry tracing support by @chrisguidry in https://github.com/PrefectHQ/fastmcp/pull/2869
- Add component versioning and VersionFilter transform by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2894
- Add version discovery and calling a certain version for components by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2897
- Refactor visibility to mark-based enabled system by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2912
- Add session-specific visibility control via Context by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2917
- Add Skills Provider for exposing agent skills as MCP resources by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2944
- Add MCP Apps Phase 1 β SDK compatibility (SEP-1865) by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3009
- Add
fastmcp listandfastmcp callCLI commands by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3054 - Add
fastmcp generate-clicommand by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3065 - Add CIMD (Client ID Metadata Document) support for OAuth by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2871
Enhancements π§
- Convert mounted servers to MountedProvider by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2635
- Simplify .key as computed property by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2648
- Refactor MountedProvider into FastMCPProvider + TransformingProvider by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2653
- Enable background task support for custom component subclasses by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2657
- Use CreateTaskResult for background task creation by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2660
- Refactor provider execution: components own their execution by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2663
- Add supports_tasks() method to replace string mode checks by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2664
- Replace type: ignore[attr-defined] with isinstance assertions in tests by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2665
- Add poll_interval to TaskConfig by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2666
- Refactor task module: rename protocol.py to requests.py and reduce redundancy by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2667
- Refactor FastMCPProxy into ProxyProvider by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2669
- Move OpenAPI to providers/openapi submodule by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2672
- Use ergonomic provider initialization pattern by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2675
- Fix ty 0.0.5 type errors by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2676
- Remove execution methods from Provider base class by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2681
- Add type-prefixed keys for globally unique component identification by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2704
- Skip parallel MCP config test on Windows by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2711
- Consolidate notification system with unified API by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2710
- Skip test_multi_client on Windows by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2714
- Parallelize provider operations by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2716
- Consolidate get_* and list* methods into single API by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2719
- Consolidate execution method chains into single public API by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2728
- Add documentation check to required PR workflow by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2730
- Parallelize list_* calls in Provider.get_tasks() by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2731
Fixes π
- Let FastMCPError propagate from dependencies by @chrisguidry in https://github.com/PrefectHQ/fastmcp/pull/2646
- Fix task execution for tools with custom names by @chrisguidry in https://github.com/PrefectHQ/fastmcp/pull/2645
- fix: check the cause of the tool error by @rjolaverria in https://github.com/PrefectHQ/fastmcp/pull/2674
- Bump pydocket to 0.16.3 for task cancellation support by @chrisguidry in https://github.com/PrefectHQ/fastmcp/pull/2683
- Fix uvicorn 0.39+ test timeouts and FastMCPError propagation by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2699
- Fix Prefect website URL in docs footer by @mgoldsborough in https://github.com/PrefectHQ/fastmcp/pull/2701
- Fix: resolve root-level $ref in outputSchema for MCP spec compliance by @majiayu000 in https://github.com/PrefectHQ/fastmcp/pull/2720
- Fix Provider.get_tasks() to include custom component subclasses by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2729
- Fix Proxy provider to return all resource contents by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2742
- Fix prompt return type documentation by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2741
- fix: Client OAuth async_auth_flow() method causing MCP-SDK self.context.lock error. by @lgndluke in https://github.com/PrefectHQ/fastmcp/pull/2644
- Fix rate limit detection during teardown phase by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2757
- fix: set pytest-asyncio default fixture loop scope to function by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2758
- Fix OAuth Proxy resource parameter validation by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2764
- [BugFix] Fix
openapi_versionCheck So 3.1 Is Included by @deeleeramone in https://github.com/PrefectHQ/fastmcp/pull/2768 - Fix titled enum elicitation schema to comply with MCP spec by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2773
- Fix base_url fallback when url is not set by @bhbs in https://github.com/PrefectHQ/fastmcp/pull/2776
- Lazy import DiskStore to avoid sqlite3 dependency on import by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2784
- Fix OAuth token storage TTL calculation by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2796
- Use consistent refresh_ttl for JTI mapping store by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2799
- Return 401 for invalid_grant token errors per MCP spec by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2800
- Fix client hanging on HTTP 4xx/5xx errors by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2803
- Fix unawaited coroutine warning and treat as test error by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2806
- Fix keep_alive passthrough in StdioMCPServer.to_transport() by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2791
Breaking Changes π«
- Add VisibilityFilter for hierarchical enable/disable by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2708
- Remove automatic environment variable loading from auth providers by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2752
- Make pydocket optional and unify DI systems by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2835
- Add session-scoped state persistence by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2873
- Rename ui= to app= and consolidate ToolUI/ResourceUI into AppConfig by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3117
- Remove deprecated FastMCP() constructor kwargs by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3148
- Move
fastmcp devtofastmcp dev inspectorby @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3188
Docs π
- Undocumented
McpErrorexceptions by @ivanbelenky in https://github.com/PrefectHQ/fastmcp/pull/2656 - docs(server): add http to transport options in run() method docstring by @Ashif4354 in https://github.com/PrefectHQ/fastmcp/pull/2707
- Add v3 breaking changes notice to README by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2712
- Add changelog entries for v2.13.1 through v2.14.1 by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2725
- Reorganize docs around provider architecture by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2723
- Fix documentation to use 'meta' instead of '_meta' for MCP spec field by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2735
- Enhance documentation on tool transformation by @shea-parkes in https://github.com/PrefectHQ/fastmcp/pull/2781
- Add FastMCP 4.0 preview to documentation by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2831
- Add release notes for v2.14.2 and v2.14.3 by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2852
- Add missing 3.0.0 version badges and document tasks extra by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2866
- Add missing v3 features to tracking docs by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2888
- Fix custom provider docs to show correct interface by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2920
- Update v3 features that were missed in PRs by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2947
- Restructure documentation for FastMCP 3.0 by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2951
- Fix broken documentation links by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2952
- Clarify installation for FastMCP 3.0 beta by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2953
- Prepare docs for v3.0 beta release by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2954
- Restructure docs: move transforms to dedicated section by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2956
- Remove unecessary pip warning by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2958
- Update example MCP version in installation docs by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2959
- Update brand images by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2960
- Restructure README and welcome page with motivated narrative by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2963
- Restructure README and docs with motivated narrative by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2964
- Favicon update and Prefect Horizon docs by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2978
- Add dependency injection documentation and DI-style dependencies by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2980
Dependencies π¦
- Bump peter-evans/create-pull-request from 7 to 8 by @dependabot[bot] in https://github.com/PrefectHQ/fastmcp/pull/2623
- Bump ty to 0.0.7+ by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/2737
- Bump the uv group across 1 directory with 4 updates by @dependabot[bot] in https://github.com/PrefectHQ/fastmcp/pull/2891
- Bump ty from 0.0.12 to 0.0.13 by @dependabot[bot] in https://github.com/PrefectHQ/fastmcp/pull/2984
- Bump prek from 0.2.30 to 0.3.0 by @dependabot[bot] in https://github.com/PrefectHQ/fastmcp/pull/2982
- chore(deps): bump cryptography from 46.0.3 to 46.0.5 in /examples/testing_demo in the uv group across 1 directory by @dependabot[bot] in https://github.com/PrefectHQ/fastmcp/pull/3140
- chore(deps): bump cryptography from 46.0.4 to 46.0.5 in the uv group across 1 directory by @dependabot[bot] in https://github.com/PrefectHQ/fastmcp/pull/3147
Other Changes π¦Ύ
- Normalize resource URLs before comparison to support RFC 8707 query parameters by @abhijeethp in https://github.com/PrefectHQ/fastmcp/pull/2967
- Bump pydocket to 0.17.2 (memory leak fix) by @chrisguidry in https://github.com/PrefectHQ/fastmcp/pull/2998
- Add AzureJWTVerifier for Managed Identity token verification by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3058
- Add release notes for v2.14.4 and v2.14.5 by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3064
- docs: add v3.0.0rc1 features to v3-features tracking by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3145
- docs: remove nonexistent MSALApp from rc1 notes by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3146
New Contributors
- @ivanbelenky made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2656
- @rjolaverria made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2674
- @mgoldsborough made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2701
- @Ashif4354 made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2707
- @majiayu000 made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2720
- @lgndluke made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2644
- @EloiZalczer made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2632
- @deeleeramone made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2768
- @shea-parkes made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2781
- @bryankthompson made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2777
- @bhbs made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2776
- @shulkx made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2884
- @abhijeethp made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2967
- @aminsamir45 made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/3005
- @JonasKs made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2997
- @NeelayS made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/3057
- @gfortaine made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2905
- @nathanwelsh8 made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/3066
- @dgenio made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2885
- @martimfasantos made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/3086
- @jfBiswajit made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/3193
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v2.14.5...v3.0.0