docs: separate beta1 and beta2 features in v3-features

- Add H2 section for 3.0.0beta2 with expanded reload feature - Add H2 section for 3.0.0beta1 - Bump all beta1 features from H2 to H3 - Bump all subsections from H3 to H4 Co-authored-by: Jeremiah Lowin <jlowin@users.noreply.github.com>
2026-08-09 07:09:11 +02:00 · 2026-01-30 03:09:21 +00:00
1 changed files with 54 additions and 44 deletions
--- a/docs/development/v3-notes/v3-features.mdx
+++ b/docs/development/v3-notes/v3-features.mdx
@ -4,7 +4,17 @@ title: v3.0 Feature Tracking

 This document tracks major features in FastMCP v3.0 for release notes preparation.

-## Provider-Based Architecture
+## 3.0.0beta2
+
+### Expanded CLI Auto-Reload
+
+The `--reload` flag now watches a variety of file types beyond Python files ([#3028](https://github.com/jlowin/fastmcp/pull/3028)), enabling seamless development for MCP apps that include frontend bundles. The implementation automatically detects changes to JavaScript, TypeScript, CSS, HTML, and other common web development file types, triggering server restarts when needed.
+
+---
+
+## 3.0.0beta1
+
+### Provider-Based Architecture

 v3.0 introduces a provider-based component system that replaces v2's static-only registration ([#2622](https://github.com/jlowin/fastmcp/pull/2622)). Providers dynamically source tools, resources, templates, and prompts at runtime.

@ -26,7 +36,7 @@ Providers support:
 - **Visibility control**: `enable()` / `disable()` with name, version, tags, components, and allowlist mode
 - **Transform stacking**: `provider.add_transform(Namespace(...))`, `provider.add_transform(ToolTransform(...))`

-### LocalProvider
+#### LocalProvider

 `LocalProvider` (`src/fastmcp/server/providers/local_provider.py`) manages components registered via decorators. Can be used standalone and attached to multiple servers:

@ -44,7 +54,7 @@ server1 = FastMCP("Server1", providers=[provider])
 server2 = FastMCP("Server2", providers=[provider])
 ```

-### ProxyProvider
+#### ProxyProvider

 `ProxyProvider` (`src/fastmcp/server/providers/proxy.py`) proxies components from remote MCP servers via a client factory. Used by `create_proxy()` and `FastMCP.mount()` for remote server integration.

@ -55,7 +65,7 @@ from fastmcp.server import create_proxy
 server = create_proxy("http://remote-server/mcp")
 ```

-### OpenAPIProvider
+#### OpenAPIProvider

 `OpenAPIProvider` (`src/fastmcp/server/providers/openapi/provider.py`) creates MCP components from OpenAPI specifications. Routes map HTTP operations to tools, resources, or templates based on configurable rules.

@ -75,7 +85,7 @@ Features:
 - Component customization via `mcp_component_fn`
 - Name collision detection and handling

-### FastMCPProvider
+#### FastMCPProvider

 `FastMCPProvider` (`src/fastmcp/server/providers/fastmcp_provider.py`) wraps a FastMCP server to enable mounting one server onto another. Components delegate execution through the wrapped server's middleware chain.

@ -98,7 +108,7 @@ main.add_provider(provider)
 # Tool accessible as "sub_greet"
 ```

-### Transforms
+#### Transforms

 Transforms modify components (tools, resources, prompts) as they flow from providers to clients ([#2836](https://github.com/jlowin/fastmcp/pull/2836)). They use a middleware pattern where each transform receives a `call_next` callable to continue the chain.

@ -151,7 +161,7 @@ Transforms apply at two levels:

 Documentation: `docs/servers/transforms/transforms.mdx`, `docs/servers/visibility.mdx`

-### ResourcesAsTools and PromptsAsTools
+#### ResourcesAsTools and PromptsAsTools

 These transforms expose resources and prompts as tools for clients that only support the tools protocol. Each transform generates two tools that provide listing and access functionality.

@ -201,7 +211,7 @@ Documentation: `docs/servers/transforms/resources-as-tools.mdx`, `docs/servers/t

 ---

-## Session-Scoped State
+### Session-Scoped State

 v3.0 changes context state from request-scoped to session-scoped. State now persists across multiple tool calls within the same MCP session.

@ -232,7 +242,7 @@ Documentation: `docs/servers/context.mdx`

 ---

-## Visibility System
+### Visibility System

 Components can be enabled/disabled using the visibility system. Each `enable()` or `disable()` call adds a stateless Visibility transform that marks components via internal metadata. Later transforms override earlier ones.

@ -263,7 +273,7 @@ Works at both server and provider level. Supports:
 - **Override semantics**: Later transforms override earlier marks (enable after disable = enabled)
 - **Transform ordering**: Visibility transforms are injected at the point you call them, so component state is known

-### Per-Session Visibility
+#### Per-Session Visibility

 Server-level visibility changes affect all connected clients. For per-session control, use `Context` methods that apply rules only to the current session ([#2917](https://github.com/jlowin/fastmcp/pull/2917)):

@ -304,7 +314,7 @@ Documentation: `docs/servers/visibility.mdx`

 ---

-## Component Versioning
+### Component Versioning

 v3.0 introduces versioning support for tools, resources, and prompts. Components can declare a version, and when multiple versions of the same component exist, the highest version is automatically exposed to clients.

@ -422,11 +432,11 @@ The `@` is always present (even for unversioned components) to enable unambiguou

 ---

-## Type-Safe Canonical Results
+### Type-Safe Canonical Results

 v3.0 introduces type-safe result classes that provide explicit control over component responses while supporting MCP runtime metadata: `ToolResult` ([#2736](https://github.com/jlowin/fastmcp/pull/2736)), `ResourceResult` ([#2734](https://github.com/jlowin/fastmcp/pull/2734)), and `PromptResult` ([#2738](https://github.com/jlowin/fastmcp/pull/2738)).

-### ToolResult
+#### ToolResult

 `ToolResult` (`src/fastmcp/tools/tool.py:79`) provides structured tool responses:

@ -447,7 +457,7 @@ Fields:
 - `structured_content`: Dict matching tool's output schema
 - `meta`: Runtime metadata passed to MCP as `_meta`

-### ResourceResult
+#### ResourceResult

 `ResourceResult` (`src/fastmcp/resources/resource.py:117`) provides structured resource responses:

@ -467,7 +477,7 @@ def get_items() -> ResourceResult:

 Accepts strings, bytes, or `list[ResourceContent]` for flexible content handling.

-### PromptResult
+#### PromptResult

 `PromptResult` (`src/fastmcp/prompts/prompt.py:109`) provides structured prompt responses:

@ -487,7 +497,7 @@ def conversation() -> PromptResult:

 ---

-## Background Tasks (SEP-1686)
+### Background Tasks (SEP-1686)

 v3.0 implements MCP SEP-1686 for background task execution via Docket integration.

@ -520,7 +530,7 @@ Requires Docket server for task scheduling and result polling.

 ---

-## Decorators Return Functions
+#### Decorators Return Functions

 v3.0 changes what decorators (`@tool`, `@resource`, `@prompt`) return ([#2856](https://github.com/jlowin/fastmcp/pull/2856)). Decorators now return the original function unchanged, rather than transforming it into a component object.

@ -552,7 +562,7 @@ Environment variable: `FASTMCP_DECORATOR_MODE=object`

 ---

-## CLI Auto-Reload
+### CLI Auto-Reload

 The `--reload` flag enables file watching with automatic server restarts for development ([#2816](https://github.com/jlowin/fastmcp/pull/2816)).

@ -581,7 +591,7 @@ fastmcp dev server.py  # Includes --reload by default

 ---

-## Component Authorization
+### Component Authorization

 v3.0 introduces callable-based authorization for tools, resources, and prompts ([#2855](https://github.com/jlowin/fastmcp/pull/2855)).

@ -634,7 +644,7 @@ STDIO transport bypasses all auth checks (no OAuth concept).

 ---

-## MCP Apps (SDK Compatibility)
+### MCP Apps (SDK Compatibility)

 v3.0 adds Phase 1 support for [MCP Apps](https://modelcontextprotocol.io/specification/2025-06-18/server/apps) — the spec extension that lets MCP servers deliver interactive UIs via sandboxed iframes. Phase 1 is SDK compatibility only: extension negotiation, typed UI metadata on tools and resources, and the `ui://` resource scheme. No component DSL, renderer, or `FastMCPApp` class yet — those are future phases.

@ -698,7 +708,7 @@ Implementation: `src/fastmcp/server/apps.py` (models and constants), with integr

 ---

-## FileSystemProvider
+### FileSystemProvider

 v3.0 introduces `FileSystemProvider`, a fundamentally different approach to organizing MCP servers. Instead of importing a server instance and decorating functions with `@server.tool`, you use standalone decorators in separate files and let the provider discover them.

@ -736,7 +746,7 @@ Documentation: [FileSystemProvider](/servers/providers/filesystem)

 ---

-## SkillsProvider
+### SkillsProvider

 v3.0 introduces `SkillsProvider` for exposing agent skills as MCP resources ([#2944](https://github.com/jlowin/fastmcp/pull/2944)). Skills are directories containing instructions and supporting files that teach AI assistants how to perform tasks—used by Claude Code, Cursor, VS Code Copilot, and other AI coding tools.

@ -779,7 +789,7 @@ Documentation: [Skills Provider](/servers/providers/skills)

 ---

-## OpenTelemetry Tracing
+### OpenTelemetry Tracing

 v3.0 adds OpenTelemetry instrumentation for observability into server and client operations ([#2869](https://github.com/jlowin/fastmcp/pull/2869)).

@ -807,7 +817,7 @@ Documentation: [Telemetry](/servers/telemetry)

 ---

-## Pagination
+### Pagination

 v3.0 adds pagination support for list operations when servers expose many components ([#2903](https://github.com/jlowin/fastmcp/pull/2903)).

@ -833,7 +843,7 @@ Documentation: [Pagination](/servers/pagination)

 ---

-## Composable Lifespans
+### Composable Lifespans

 Lifespans can be combined with the `|` operator for modular setup/teardown ([#2828](https://github.com/jlowin/fastmcp/pull/2828)):

@ -874,7 +884,7 @@ Documentation: [Lifespan](/servers/lifespan)

 ---

-## Tool Timeout
+### Tool Timeout

 Tools can limit foreground execution time with a `timeout` parameter ([#2872](https://github.com/jlowin/fastmcp/pull/2872)):

@ -891,7 +901,7 @@ Note: This timeout applies to foreground execution only. Background tasks (`task

 ---

-## PingMiddleware
+### PingMiddleware

 Sends periodic server-to-client pings to keep long-lived connections alive ([#2838](https://github.com/jlowin/fastmcp/pull/2838)):

@ -907,7 +917,7 @@ The middleware starts a background ping task on first message from each session,

 ---

-## Context.transport Property
+### Context.transport Property

 Tools can detect which transport is active ([#2850](https://github.com/jlowin/fastmcp/pull/2850)):

@ -927,7 +937,7 @@ Returns `Literal["stdio", "sse", "streamable-http"]` when running, or `None` out

 ---

-## Automatic Threadpool for Sync Functions
+### Automatic Threadpool for Sync Functions

 Synchronous tools, resources, and prompts now automatically run in a threadpool, preventing event loop blocking during concurrent requests ([#2865](https://github.com/jlowin/fastmcp/pull/2865)):

@ -944,7 +954,7 @@ Three concurrent calls now execute in parallel (~10s) rather than sequentially (

 ---

-## CLI Update Notifications
+### CLI Update Notifications

 The CLI notifies users when a newer FastMCP version is available on PyPI ([#2840](https://github.com/jlowin/fastmcp/pull/2840)).

@ -957,11 +967,11 @@ The CLI notifies users when a newer FastMCP version is available on PyPI ([#2840

 ---

-## Deprecated Features
+### Deprecated Features

 These emit deprecation warnings but continue to work.

-### Mount Prefix Parameter
+#### Mount Prefix Parameter

 The `prefix` parameter for `mount()` renamed to `namespace`:

@ -973,7 +983,7 @@ main.mount(subserver, prefix="api")
 main.mount(subserver, namespace="api")
 ```

-### Tag Filtering Init Parameters
+#### Tag Filtering Init Parameters

 `FastMCP(include_tags=..., exclude_tags=...)` deprecated. Use `enable()`/`disable()` methods:

@ -986,11 +996,11 @@ mcp = FastMCP("server")
 mcp.disable(tags={"internal"})
 ```

-### Tool Serializer Parameter
+#### Tool Serializer Parameter

 The `tool_serializer` parameter on `FastMCP` is deprecated. Return `ToolResult` for explicit serialization control.

-### Tool Transformation Methods
+#### Tool Transformation Methods

 `add_tool_transformation()`, `remove_tool_transformation()`, and `tool_transformations` constructor parameter are deprecated. Use `add_transform(ToolTransform({...}))` instead:

@ -1005,13 +1015,13 @@ mcp.add_transform(ToolTransform({"name": config}))

 ---

-## Breaking Changes
+### Breaking Changes

-### WSTransport Removed
+#### WSTransport Removed

 The deprecated `WSTransport` client transport has been removed ([#2826](https://github.com/jlowin/fastmcp/pull/2826)). Use `StreamableHttpTransport` instead.

-### Decorators Return Functions
+##### Decorators Return Functions

 Decorators (`@tool`, `@resource`, `@prompt`) now return the original function instead of component objects. Code that treats the decorated function as a `FunctionTool`, `FunctionResource`, or `FunctionPrompt` will break.

@ -1035,7 +1045,7 @@ greet("World")                   # "Hello, World!"

 Set `FASTMCP_DECORATOR_MODE=object` or `fastmcp.settings.decorator_mode = "object"` for v2 behavior.

-### Component Enable/Disable Moved to Server/Provider
+#### Component Enable/Disable Moved to Server/Provider

 The `enabled` field and `enable()`/`disable()` methods removed from component objects:

@ -1048,7 +1058,7 @@ tool.disable()
 server.disable(names={"my_tool"}, components=["tool"])
 ```

-### Component Lookup Methods
+#### Component Lookup Methods

 Server lookup and listing methods have updated signatures:

@ -1065,7 +1075,7 @@ tools = await server.get_tools()
 tool = next((t for t in tools if t.name == "my_tool"), None)
 ```

-### Prompt Return Types
+#### Prompt Return Types

 Prompt functions now use `Message` instead of `mcp.types.PromptMessage`:

@ -1085,7 +1095,7 @@ def my_prompt() -> Message:
    return Message("Hello")  # role defaults to "user"
 ```

-### Auth Provider Environment Variables Removed
+#### Auth Provider Environment Variables Removed

 Auth providers no longer auto-load from environment variables ([#2752](https://github.com/jlowin/fastmcp/pull/2752)):

@ -1103,13 +1113,13 @@ auth = GitHubProvider(

 See `docs/development/v3-notes/auth-provider-env-vars.mdx` for rationale.

-### Server Banner Environment Variable
+#### Server Banner Environment Variable

 `FASTMCP_SHOW_CLI_BANNER` → `FASTMCP_SHOW_SERVER_BANNER` ([#2771](https://github.com/jlowin/fastmcp/pull/2771))

 Now applies to all server startup methods, not just the CLI.

-### Context State Methods Are Async
+#### Context State Methods Are Async

 `ctx.set_state()` and `ctx.get_state()` are now async and session-scoped: