Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

chore: Update SDK documentation (#2604)

marvin-context-protocol[bot]9d5ffa86b361
diff --git a/docs/docs.json b/docs/docs.json
index 4a6b4bd59..60a072fcb 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -320,7 +320,20 @@
"python-sdk/fastmcp-client-oauth_callback",
"python-sdk/fastmcp-client-progress",
"python-sdk/fastmcp-client-roots",
- "python-sdk/fastmcp-client-sampling",
+ {
+ "group": "sampling",
+ "pages": [
+ "python-sdk/fastmcp-client-sampling-__init__",
+ {
+ "group": "handlers",
+ "pages": [
+ "python-sdk/fastmcp-client-sampling-handlers-__init__",
+ "python-sdk/fastmcp-client-sampling-handlers-anthropic",
+ "python-sdk/fastmcp-client-sampling-handlers-openai"
+ ]
+ }
+ ]
+ },
"python-sdk/fastmcp-client-tasks",
"python-sdk/fastmcp-client-transports"
]
@@ -329,8 +342,7 @@
"group": "fastmcp.prompts",
"pages": [
"python-sdk/fastmcp-prompts-__init__",
- "python-sdk/fastmcp-prompts-prompt",
- "python-sdk/fastmcp-prompts-prompt_manager"
+ "python-sdk/fastmcp-prompts-prompt"
]
},
{
@@ -338,7 +350,6 @@
"pages": [
"python-sdk/fastmcp-resources-__init__",
"python-sdk/fastmcp-resources-resource",
- "python-sdk/fastmcp-resources-resource_manager",
"python-sdk/fastmcp-resources-template",
"python-sdk/fastmcp-resources-types"
]
@@ -408,7 +419,35 @@
"python-sdk/fastmcp-server-openapi-server"
]
},
+ {
+ "group": "providers",
+ "pages": [
+ "python-sdk/fastmcp-server-providers-__init__",
+ "python-sdk/fastmcp-server-providers-base",
+ "python-sdk/fastmcp-server-providers-fastmcp_provider",
+ "python-sdk/fastmcp-server-providers-local_provider",
+ {
+ "group": "openapi",
+ "pages": [
+ "python-sdk/fastmcp-server-providers-openapi-__init__",
+ "python-sdk/fastmcp-server-providers-openapi-components",
+ "python-sdk/fastmcp-server-providers-openapi-provider",
+ "python-sdk/fastmcp-server-providers-openapi-routing"
+ ]
+ },
+ "python-sdk/fastmcp-server-providers-proxy",
+ "python-sdk/fastmcp-server-providers-transforming"
+ ]
+ },
"python-sdk/fastmcp-server-proxy",
+ {
+ "group": "sampling",
+ "pages": [
+ "python-sdk/fastmcp-server-sampling-__init__",
+ "python-sdk/fastmcp-server-sampling-run",
+ "python-sdk/fastmcp-server-sampling-sampling_tool"
+ ]
+ },
"python-sdk/fastmcp-server-server",
{
"group": "tasks",
@@ -416,10 +455,10 @@
"python-sdk/fastmcp-server-tasks-__init__",
"python-sdk/fastmcp-server-tasks-capabilities",
"python-sdk/fastmcp-server-tasks-config",
- "python-sdk/fastmcp-server-tasks-converters",
"python-sdk/fastmcp-server-tasks-handlers",
"python-sdk/fastmcp-server-tasks-keys",
- "python-sdk/fastmcp-server-tasks-protocol",
+ "python-sdk/fastmcp-server-tasks-requests",
+ "python-sdk/fastmcp-server-tasks-routing",
"python-sdk/fastmcp-server-tasks-subscriptions"
]
}
@@ -430,7 +469,6 @@
"pages": [
"python-sdk/fastmcp-tools-__init__",
"python-sdk/fastmcp-tools-tool",
- "python-sdk/fastmcp-tools-tool_manager",
"python-sdk/fastmcp-tools-tool_transform"
]
},
@@ -491,7 +529,8 @@
},
"python-sdk/fastmcp-utilities-tests",
"python-sdk/fastmcp-utilities-types",
- "python-sdk/fastmcp-utilities-ui"
+ "python-sdk/fastmcp-utilities-ui",
+ "python-sdk/fastmcp-utilities-visibility"
]
}
]
diff --git a/docs/python-sdk/fastmcp-client-client.mdx b/docs/python-sdk/fastmcp-client-client.mdx
index 95907eb4f..eb9f152e7 100644
--- a/docs/python-sdk/fastmcp-client-client.mdx
+++ b/docs/python-sdk/fastmcp-client-client.mdx
@@ -7,7 +7,7 @@ sidebarTitle: client
## Classes
-### `ClientSessionState` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ClientSessionState` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Holds all session-related state for a Client instance.
@@ -16,13 +16,13 @@ This allows clean separation of configuration (which is copied) from
session state (which should be fresh for each new client instance).
-### `CallToolResult` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `CallToolResult` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Parsed result from a tool call.
-### `Client` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `Client` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
MCP client that delegates connection management to a Transport instance.
@@ -85,7 +85,7 @@ async with client:
**Methods:**
-#### `session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L329" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L349" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
session(self) -> ClientSession
@@ -94,7 +94,7 @@ session(self) -> ClientSession
Get the current active session. Raises RuntimeError if not connected.
-#### `initialize_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L339" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `initialize_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L359" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
initialize_result(self) -> mcp.types.InitializeResult | None
@@ -103,7 +103,7 @@ initialize_result(self) -> mcp.types.InitializeResult | None
Get the result of the initialization request.
-#### `set_roots` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L343" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_roots` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L363" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
set_roots(self, roots: RootsList | RootsHandler) -> None
@@ -112,16 +112,16 @@ set_roots(self, roots: RootsList | RootsHandler) -> None
Set the roots for the client. This does not automatically call `send_roots_list_changed`.
-#### `set_sampling_callback` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L347" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_sampling_callback` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L367" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-set_sampling_callback(self, sampling_callback: ClientSamplingHandler) -> None
+set_sampling_callback(self, sampling_callback: SamplingHandler, sampling_capabilities: mcp.types.SamplingCapability | None = None) -> None
```
Set the sampling callback for the client.
-#### `set_elicitation_callback` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L353" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_elicitation_callback` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L383" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
set_elicitation_callback(self, elicitation_callback: ElicitationHandler) -> None
@@ -130,7 +130,7 @@ set_elicitation_callback(self, elicitation_callback: ElicitationHandler) -> None
Set the elicitation callback for the client.
-#### `is_connected` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L361" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `is_connected` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L391" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
is_connected(self) -> bool
@@ -139,7 +139,7 @@ is_connected(self) -> bool
Check if the client is currently connected.
-#### `new` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L365" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `new` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L395" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
new(self) -> Client[ClientTransportT]
@@ -155,7 +155,7 @@ share state with the original client.
- A new Client instance with the same configuration but disconnected state.
-#### `initialize` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L411" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `initialize` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L440" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
initialize(self, timeout: datetime.timedelta | float | int | None = None) -> mcp.types.InitializeResult
@@ -183,13 +183,13 @@ capabilities, protocol version, and optional instructions.
- `RuntimeError`: If the client is not connected or initialization times out.
-#### `close` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L613" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `close` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L680" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
close(self)
```
-#### `ping` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L619" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `ping` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L686" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
ping(self) -> bool
@@ -198,7 +198,7 @@ ping(self) -> bool
Send a ping request.
-#### `cancel` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L624" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `cancel` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L691" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
cancel(self, request_id: str | int, reason: str | None = None) -> None
@@ -207,7 +207,7 @@ cancel(self, request_id: str | int, reason: str | None = None) -> None
Send a cancellation notification for an in-progress request.
-#### `progress` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L641" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `progress` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L708" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
progress(self, progress_token: str | int, progress: float, total: float | None = None, message: str | None = None) -> None
@@ -216,7 +216,7 @@ progress(self, progress_token: str | int, progress: float, total: float | None =
Send a progress notification.
-#### `set_logging_level` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L653" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_logging_level` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L720" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
set_logging_level(self, level: mcp.types.LoggingLevel) -> None
@@ -225,7 +225,7 @@ set_logging_level(self, level: mcp.types.LoggingLevel) -> None
Send a logging/setLevel request.
-#### `send_roots_list_changed` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L657" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `send_roots_list_changed` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L724" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
send_roots_list_changed(self) -> None
@@ -234,7 +234,7 @@ send_roots_list_changed(self) -> None
Send a roots/list_changed notification.
-#### `list_resources_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L663" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_resources_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L730" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_resources_mcp(self) -> mcp.types.ListResourcesResult
@@ -248,9 +248,10 @@ containing the list of resources and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L678" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L746" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_resources(self) -> list[mcp.types.Resource]
@@ -263,9 +264,10 @@ Retrieve a list of resources available on the server.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_resource_templates_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L690" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_resource_templates_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L759" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_resource_templates_mcp(self) -> mcp.types.ListResourceTemplatesResult
@@ -279,9 +281,10 @@ containing the list of resource templates and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L707" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L777" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_resource_templates(self) -> list[mcp.types.ResourceTemplate]
@@ -294,9 +297,10 @@ Retrieve a list of resource templates available on the server.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `read_resource_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L721" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read_resource_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L792" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
read_resource_mcp(self, uri: AnyUrl | str, meta: dict[str, Any] | None = None) -> mcp.types.ReadResourceResult
@@ -314,21 +318,22 @@ containing the resource contents and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L762" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L834" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
read_resource(self, uri: AnyUrl | str) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]
```
-#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L770" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L842" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
read_resource(self, uri: AnyUrl | str) -> ResourceTask
```
-#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L779" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L851" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
read_resource(self, uri: AnyUrl | str) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents] | ResourceTask
@@ -348,9 +353,10 @@ A list of content objects if task=False, or a ResourceTask object if task=True.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_prompts_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L888" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_prompts_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L964" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_prompts_mcp(self) -> mcp.types.ListPromptsResult
@@ -364,9 +370,10 @@ containing the list of prompts and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L903" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L980" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_prompts(self) -> list[mcp.types.Prompt]
@@ -379,9 +386,10 @@ Retrieve a list of prompts available on the server.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `get_prompt_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L916" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_prompt_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_prompt_mcp(self, name: str, arguments: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) -> mcp.types.GetPromptResult
@@ -400,21 +408,22 @@ containing the prompt messages and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L974" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1053" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.GetPromptResult
```
-#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L983" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1062" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> PromptTask
```
-#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L993" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1072" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.GetPromptResult | PromptTask
@@ -435,9 +444,10 @@ or a PromptTask object if task=True.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `complete_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1085" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `complete_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1174" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
complete_mcp(self, ref: mcp.types.ResourceTemplateReference | mcp.types.PromptReference, argument: dict[str, str], context_arguments: dict[str, Any] | None = None) -> mcp.types.CompleteResult
@@ -457,9 +467,10 @@ containing the completion and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `complete` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `complete` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1203" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
complete(self, ref: mcp.types.ResourceTemplateReference | mcp.types.PromptReference, argument: dict[str, str], context_arguments: dict[str, Any] | None = None) -> mcp.types.Completion
@@ -478,9 +489,10 @@ include with the completion request. Defaults to None.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_tools_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_tools_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1231" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_tools_mcp(self) -> mcp.types.ListToolsResult
@@ -494,9 +506,10 @@ containing the list of tools and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1247" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_tools(self) -> list[mcp.types.Tool]
@@ -509,9 +522,10 @@ Retrieve a list of tools available on the server.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `call_tool_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `call_tool_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1262" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
call_tool_mcp(self, name: str, arguments: dict[str, Any], progress_handler: ProgressHandler | None = None, timeout: datetime.timedelta | float | int | None = None, meta: dict[str, Any] | None = None) -> mcp.types.CallToolResult
@@ -538,21 +552,22 @@ containing the tool result and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the tool call requests results in a TimeoutError | JSONRPCError
-#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1282" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1356" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult
```
-#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1295" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> ToolTask
```
-#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1383" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult | ToolTask
@@ -587,10 +602,11 @@ raw result object.
**Raises:**
- `ToolError`: If the tool call results in an error.
+- `McpError`: If the tool call request results in a TimeoutError | JSONRPCError
- `RuntimeError`: If called while the client is not connected.
-#### `get_task_status` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_task_status` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1503" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_task_status(self, task_id: str) -> GetTaskResult
@@ -608,9 +624,10 @@ Sends a 'tasks/get' MCP protocol request over the existing transport.
**Raises:**
- `RuntimeError`: If client not connected
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `get_task_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1451" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_task_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1524" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_task_result(self, task_id: str) -> Any
@@ -629,9 +646,10 @@ Returns the raw result - callers should parse it appropriately.
**Raises:**
- `RuntimeError`: If client not connected, task not found, or task failed
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_tasks` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1477" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_tasks` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1551" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_tasks(self, cursor: str | None = None, limit: int = 50) -> dict[str, Any]
@@ -654,9 +672,10 @@ querying status for locally tracked task IDs.
**Raises:**
- `RuntimeError`: If client not connected
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `cancel_task` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1524" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `cancel_task` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1599" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
cancel_task(self, task_id: str) -> mcp.types.CancelTaskResult
@@ -675,9 +694,10 @@ and transition to cancelled state.
**Raises:**
- `RuntimeError`: If task doesn't exist
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `generate_name` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1546" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `generate_name` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1622" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
generate_name(cls, name: str | None = None) -> str
diff --git a/docs/python-sdk/fastmcp-client-sampling-__init__.mdx b/docs/python-sdk/fastmcp-client-sampling-__init__.mdx
new file mode 100644
index 000000000..ec69f61c7
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-sampling-__init__.mdx
@@ -0,0 +1,14 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.client.sampling`
+
+## Functions
+
+### `create_sampling_callback` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/sampling/__init__.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_sampling_callback(sampling_handler: SamplingHandler) -> SamplingFnT
+```
diff --git a/docs/python-sdk/fastmcp-client-sampling-handlers-__init__.mdx b/docs/python-sdk/fastmcp-client-sampling-handlers-__init__.mdx
new file mode 100644
index 000000000..43329b5e6
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-sampling-handlers-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.client.sampling.handlers`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-client-sampling-handlers-anthropic.mdx b/docs/python-sdk/fastmcp-client-sampling-handlers-anthropic.mdx
new file mode 100644
index 000000000..b1c9af0a9
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-sampling-handlers-anthropic.mdx
@@ -0,0 +1,17 @@
+---
+title: anthropic
+sidebarTitle: anthropic
+---
+
+# `fastmcp.client.sampling.handlers.anthropic`
+
+
+Anthropic sampling handler for FastMCP.
+
+## Classes
+
+### `AnthropicSamplingHandler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/sampling/handlers/anthropic.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Sampling handler that uses the Anthropic API.
+
diff --git a/docs/python-sdk/fastmcp-client-sampling-handlers-openai.mdx b/docs/python-sdk/fastmcp-client-sampling-handlers-openai.mdx
new file mode 100644
index 000000000..08ac49f40
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-sampling-handlers-openai.mdx
@@ -0,0 +1,17 @@
+---
+title: openai
+sidebarTitle: openai
+---
+
+# `fastmcp.client.sampling.handlers.openai`
+
+
+OpenAI sampling handler for FastMCP.
+
+## Classes
+
+### `OpenAISamplingHandler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/sampling/handlers/openai.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Sampling handler that uses the OpenAI API.
+
diff --git a/docs/python-sdk/fastmcp-client-sampling.mdx b/docs/python-sdk/fastmcp-client-sampling.mdx
deleted file mode 100644
index 5fa3e70e1..000000000
--- a/docs/python-sdk/fastmcp-client-sampling.mdx
+++ /dev/null
@@ -1,14 +0,0 @@
----
-title: sampling
-sidebarTitle: sampling
----
-
-# `fastmcp.client.sampling`
-
-## Functions
-
-### `create_sampling_callback` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/sampling.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-create_sampling_callback(sampling_handler: ClientSamplingHandler[LifespanContextT]) -> SamplingFnT
-```
diff --git a/docs/python-sdk/fastmcp-client-tasks.mdx b/docs/python-sdk/fastmcp-client-tasks.mdx
index 8e8e60578..c080943d4 100644
--- a/docs/python-sdk/fastmcp-client-tasks.mdx
+++ b/docs/python-sdk/fastmcp-client-tasks.mdx
@@ -10,7 +10,7 @@ SEP-1686 client Task classes.
## Classes
-### `TaskNotificationHandler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `TaskNotificationHandler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
MessageHandler that routes task status notifications to Task objects.
@@ -18,7 +18,7 @@ MessageHandler that routes task status notifications to Task objects.
**Methods:**
-#### `dispatch` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `dispatch` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
dispatch(self, message: Message) -> None
@@ -27,7 +27,7 @@ dispatch(self, message: Message) -> None
Dispatch messages, including task status notifications.
-### `Task` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `Task` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Abstract base class for MCP background tasks (SEP-1686).
@@ -38,7 +38,7 @@ or executes synchronously (graceful degradation per SEP-1686).
**Methods:**
-#### `task_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `task_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
task_id(self) -> str
@@ -47,7 +47,7 @@ task_id(self) -> str
Get the task ID.
-#### `returned_immediately` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `returned_immediately` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
returned_immediately(self) -> bool
@@ -60,7 +60,7 @@ Check if server executed the task immediately.
- False if server accepted background execution
-#### `on_status_change` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L208" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_status_change` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_status_change(self, callback: Callable[[GetTaskResult], None | Awaitable[None]]) -> None
@@ -78,7 +78,7 @@ Supports both sync and async callbacks (auto-detected).
Can return None (sync) or Awaitable[None] (async).
-#### `status` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `status` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
status(self) -> GetTaskResult
@@ -90,7 +90,7 @@ If server executed immediately, returns synthetic completed status.
Otherwise queries the server for current status.
-#### `result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L265" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
result(self) -> TaskResultT
@@ -101,7 +101,7 @@ Wait for and return the task result.
Must be implemented by subclasses to return the appropriate result type.
-#### `wait` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `wait` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
wait(self) -> GetTaskResult
@@ -125,7 +125,7 @@ on status changes when server sends notifications/tasks/status.
- `TimeoutError`: If desired state not reached within timeout
-#### `cancel` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L335" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `cancel` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
cancel(self) -> None
@@ -140,7 +140,7 @@ Note: If server executed immediately (graceful degradation), this is a no-op
as there's no server-side task to cancel.
-### `ToolTask` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L357" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ToolTask` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L294" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Represents a tool call that may execute in background or immediately.
@@ -151,7 +151,7 @@ or executes synchronously (graceful degradation per SEP-1686).
**Methods:**
-#### `result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L399" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
result(self) -> CallToolResult
@@ -166,7 +166,7 @@ Otherwise waits for background task to complete and retrieves result.
- The parsed tool result (same as call_tool returns)
-### `PromptTask` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L459" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `PromptTask` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Represents a prompt call that may execute in background or immediately.
@@ -177,7 +177,7 @@ or executes synchronously (graceful degradation per SEP-1686).
**Methods:**
-#### `result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L490" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L427" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
result(self) -> mcp.types.GetPromptResult
@@ -192,7 +192,7 @@ Otherwise waits for background task to complete and retrieves result.
- The prompt result with messages and description
-### `ResourceTask` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L524" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ResourceTask` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L461" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Represents a resource read that may execute in background or immediately.
@@ -203,7 +203,7 @@ or executes synchronously (graceful degradation per SEP-1686).
**Methods:**
-#### `result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L560" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L497" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
result(self) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]
diff --git a/docs/python-sdk/fastmcp-client-transports.mdx b/docs/python-sdk/fastmcp-client-transports.mdx
index e34088801..410021c22 100644
--- a/docs/python-sdk/fastmcp-client-transports.mdx
+++ b/docs/python-sdk/fastmcp-client-transports.mdx
@@ -7,7 +7,7 @@ sidebarTitle: transports
## Functions
-### `infer_transport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L1058" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `infer_transport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L1077" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
infer_transport(transport: ClientTransport | FastMCP | FastMCP1Server | AnyUrl | Path | MCPConfig | dict[str, Any] | str) -> ClientTransport
@@ -63,7 +63,7 @@ transport = infer_transport(config)
Keyword arguments for the MCP ClientSession constructor.
-### `ClientTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ClientTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Abstract base class for different MCP client transport mechanisms.
@@ -74,7 +74,7 @@ to an MCP server, and providing a ClientSession within an async context.
**Methods:**
-#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
@@ -93,7 +93,7 @@ within this context.
constructor (e.g., callbacks, timeouts).
-#### `close` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `close` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
close(self)
@@ -102,7 +102,7 @@ close(self)
Close the transport.
-### `WSTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `WSTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Transport implementation that connects to an MCP server via WebSockets.
@@ -110,13 +110,13 @@ Transport implementation that connects to an MCP server via WebSockets.
**Methods:**
-#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
```
-### `SSETransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `SSETransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Transport implementation that connects to an MCP server via Server-Sent Events.
@@ -124,13 +124,13 @@ Transport implementation that connects to an MCP server via Server-Sent Events.
**Methods:**
-#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
```
-### `StreamableHttpTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L230" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `StreamableHttpTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L231" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Transport implementation that connects to an MCP server via Streamable HTTP Requests.
@@ -138,25 +138,25 @@ Transport implementation that connects to an MCP server via Streamable HTTP Requ
**Methods:**
-#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L268" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L279" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
```
-#### `get_session_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L300" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_session_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L319" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_session_id(self) -> str | None
```
-#### `close` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L308" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `close` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L327" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
close(self)
```
-### `StdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L316" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `StdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L335" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Base transport for connecting to an MCP server via subprocess with stdio.
@@ -167,67 +167,67 @@ transports like Python, Node, Uvx, etc.
**Methods:**
-#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L366" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L385" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
```
-#### `connect` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L378" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `connect` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L397" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
connect(self, **session_kwargs: Unpack[SessionKwargs]) -> ClientSession | None
```
-#### `disconnect` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L414" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `disconnect` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L433" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
disconnect(self)
```
-#### `close` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L429" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `close` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L448" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
close(self)
```
-### `PythonStdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L499" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `PythonStdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L518" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Transport for running Python scripts.
-### `FastMCPStdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L552" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `FastMCPStdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L571" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Transport for running FastMCP servers using the FastMCP CLI.
-### `NodeStdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L581" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `NodeStdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L600" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Transport for running Node.js scripts.
-### `UvStdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L634" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `UvStdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L653" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Transport for running commands via the uv tool.
-### `UvxStdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L713" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `UvxStdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L732" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Transport for running commands via the uvx tool.
-### `NpxStdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L778" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `NpxStdioTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L797" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Transport for running commands via the npx tool.
-### `FastMCPTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L840" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `FastMCPTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L859" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
In-memory transport for FastMCP servers.
@@ -240,13 +240,13 @@ tests or scenarios where client and server run in the same runtime.
**Methods:**
-#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L859" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L878" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
```
-### `MCPConfigTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L924" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `MCPConfigTransport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L943" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Transport for connecting to one or more MCP servers defined in an MCPConfig.
@@ -299,13 +299,13 @@ async with client:
**Methods:**
-#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L1006" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `connect_session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L1025" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
```
-#### `close` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L1012" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `close` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/transports.py#L1031" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
close(self)
diff --git a/docs/python-sdk/fastmcp-prompts-prompt.mdx b/docs/python-sdk/fastmcp-prompts-prompt.mdx
index fbcd6ff5a..8a24524ee 100644
--- a/docs/python-sdk/fastmcp-prompts-prompt.mdx
+++ b/docs/python-sdk/fastmcp-prompts-prompt.mdx
@@ -10,7 +10,7 @@ Base classes for FastMCP prompts.
## Functions
-### `Message` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `Message` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
Message(content: str | ContentBlock, role: Role | None = None, **kwargs: Any) -> PromptMessage
@@ -22,45 +22,62 @@ A user-friendly constructor for PromptMessage.
## Classes
-### `PromptArgument` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `PromptArgument` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
An argument that can be passed to a prompt.
-### `Prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `PromptResult` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-A prompt template that can be rendered with parameters.
+Canonical result type for prompt rendering.
+
+This is the internal type that all prompt renders return. It wraps the
+messages with optional description and metadata.
**Methods:**
-#### `enable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `from_value` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-enable(self) -> None
+from_value(cls, value: list[PromptMessage] | PromptResult, description: str | None = None, meta: dict[str, Any] | None = None) -> PromptResult
```
-#### `disable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+Convert various types to PromptResult.
+
+
+#### `to_mcp_prompt_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-disable(self) -> None
+to_mcp_prompt_result(self) -> GetPromptResult
```
-#### `to_mcp_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+Convert to MCP GetPromptResult.
+
+
+### `Prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A prompt template that can be rendered with parameters.
+
+
+**Methods:**
+
+#### `to_mcp_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-to_mcp_prompt(self, **overrides: Any) -> MCPPrompt
+to_mcp_prompt(self, **overrides: Any) -> SDKPrompt
```
Convert the prompt to an MCP prompt.
-#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L115" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-from_function(fn: Callable[..., PromptResult | Awaitable[PromptResult]], name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, tags: set[str] | None = None, enabled: bool | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionPrompt
+from_function(fn: Callable[..., _PromptFnReturn | Awaitable[_PromptFnReturn]], name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, tags: set[str] | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionPrompt
```
Create a Prompt from a function.
@@ -72,19 +89,56 @@ The function can return:
- A sequence of any of the above
-#### `render` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `render` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-render(self, arguments: dict[str, Any] | None = None) -> list[PromptMessage]
+render(self, arguments: dict[str, Any] | None = None) -> list[PromptMessage] | PromptResult
```
Render the prompt with arguments.
This method is not implemented in the base Prompt class and must be
-implemented by subclasses.
+implemented by subclasses. The preferred return type is PromptResult,
+but list\[PromptMessage] is still supported for backwards compatibility.
+
+
+#### `convert_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+convert_result(self, raw_value: Any) -> PromptResult
+```
+
+Convert a raw return value to PromptResult.
+
+Handles PromptResult passthrough and converts raw values to messages.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L279" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this prompt with docket for background execution.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, arguments: dict[str, Any] | None, **kwargs: Any) -> Execution
+```
+
+Schedule this prompt for background execution via docket.
+
+**Args:**
+- `docket`: The Docket instance
+- `arguments`: Prompt arguments
+- `fn_key`: Function lookup key in Docket registry (defaults to self.key)
+- `task_key`: Redis storage key for the result
+- `**kwargs`: Additional kwargs passed to docket.add()
-### `FunctionPrompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `FunctionPrompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
A prompt that is a function.
@@ -92,10 +146,10 @@ A prompt that is a function.
**Methods:**
-#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L315" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-from_function(cls, fn: Callable[..., PromptResult | Awaitable[PromptResult]], name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, tags: set[str] | None = None, enabled: bool | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionPrompt
+from_function(cls, fn: Callable[..., _PromptFnReturn | Awaitable[_PromptFnReturn]], name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, tags: set[str] | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionPrompt
```
Create a Prompt from a function.
@@ -107,11 +161,41 @@ The function can return:
- A sequence of any of the above
-#### `render` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L322" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `render` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L467" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-render(self, arguments: dict[str, Any] | None = None) -> list[PromptMessage]
+render(self, arguments: dict[str, Any] | None = None) -> PromptResult
```
Render the prompt with arguments.
+
+#### `register_with_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L498" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this prompt with docket for background execution.
+
+FunctionPrompt registers the underlying function, which has the user's
+Depends parameters for docket to resolve.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L508" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, arguments: dict[str, Any] | None, **kwargs: Any) -> Execution
+```
+
+Schedule this prompt for background execution via docket.
+
+FunctionPrompt splats the arguments dict since .fn expects **kwargs.
+
+**Args:**
+- `docket`: The Docket instance
+- `arguments`: Prompt arguments
+- `fn_key`: Function lookup key in Docket registry (defaults to self.key)
+- `task_key`: Redis storage key for the result
+- `**kwargs`: Additional kwargs passed to docket.add()
+
diff --git a/docs/python-sdk/fastmcp-prompts-prompt_manager.mdx b/docs/python-sdk/fastmcp-prompts-prompt_manager.mdx
deleted file mode 100644
index 30f85c18d..000000000
--- a/docs/python-sdk/fastmcp-prompts-prompt_manager.mdx
+++ /dev/null
@@ -1,71 +0,0 @@
----
-title: prompt_manager
-sidebarTitle: prompt_manager
----
-
-# `fastmcp.prompts.prompt_manager`
-
-## Classes
-
-### `PromptManager` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt_manager.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-Manages FastMCP prompts.
-
-
-**Methods:**
-
-#### `has_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt_manager.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-has_prompt(self, key: str) -> bool
-```
-
-Check if a prompt exists.
-
-
-#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt_manager.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-get_prompt(self, key: str) -> Prompt
-```
-
-Get prompt by key.
-
-
-#### `get_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt_manager.py#L53" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-get_prompts(self) -> dict[str, Prompt]
-```
-
-Gets the complete, unfiltered inventory of local prompts.
-
-
-#### `add_prompt_from_fn` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt_manager.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-add_prompt_from_fn(self, fn: Callable[..., PromptResult | Awaitable[PromptResult]], name: str | None = None, description: str | None = None, tags: set[str] | None = None) -> FunctionPrompt
-```
-
-Create a prompt from a function.
-
-
-#### `add_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt_manager.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-add_prompt(self, prompt: Prompt) -> Prompt
-```
-
-Add a prompt to the manager.
-
-
-#### `render_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/prompts/prompt_manager.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-render_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> GetPromptResult
-```
-
-Internal API for servers: Finds and renders a prompt, respecting the
-filtered protocol path.
-
diff --git a/docs/python-sdk/fastmcp-resources-resource.mdx b/docs/python-sdk/fastmcp-resources-resource.mdx
index 7ed4f805d..8a21b4f6b 100644
--- a/docs/python-sdk/fastmcp-resources-resource.mdx
+++ b/docs/python-sdk/fastmcp-resources-resource.mdx
@@ -10,33 +10,72 @@ Base classes and interfaces for FastMCP resources.
## Classes
-### `Resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ResourceContent` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-Base class for all resources.
+Canonical wrapper for resource content.
+
+This is the internal representation for all resource reads. Users can
+return ResourceContent directly for full control, or return simpler types
+(str, bytes, dict) which will be automatically converted.
**Methods:**
-#### `enable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `from_value` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-enable(self) -> None
+from_value(cls, value: Any, mime_type: str | None = None, meta: dict[str, Any] | None = None) -> ResourceContent
```
-#### `disable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+Convert any value to ResourceContent, handling serialization.
+
+**Args:**
+- `value`: The value to convert. Can be\:
+- ResourceContent\: returned as-is (meta param ignored)
+- str\: text content
+- bytes\: binary content
+- other\: serialized to JSON string
+- `mime_type`: Optional MIME type override. If not provided\:
+- str β†’ "text/plain"
+- bytes β†’ "application/octet-stream"
+- other β†’ "application/json"
+- `meta`: Optional metadata (ignored if value is already ResourceContent)
+
+**Returns:**
+- ResourceContent instance
+
+
+#### `to_mcp_resource_contents` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-disable(self) -> None
+to_mcp_resource_contents(self, uri: AnyUrl | str) -> mcp.types.TextResourceContents | mcp.types.BlobResourceContents
```
-#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+Convert to MCP resource contents type.
+
+**Args:**
+- `uri`: The URI of the resource (required by MCP types)
+
+**Returns:**
+- TextResourceContents for str content, BlobResourceContents for bytes
+
+
+### `Resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Base class for all resources.
+
+
+**Methods:**
+
+#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-from_function(fn: Callable[..., Any], uri: str | AnyUrl, name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, mime_type: str | None = None, tags: set[str] | None = None, enabled: bool | None = None, annotations: Annotations | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionResource
+from_function(fn: Callable[..., Any], uri: str | AnyUrl, name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, mime_type: str | None = None, tags: set[str] | None = None, annotations: Annotations | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionResource
```
-#### `set_default_mime_type` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_default_mime_type` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
set_default_mime_type(cls, mime_type: str | None) -> str
@@ -45,7 +84,7 @@ set_default_mime_type(cls, mime_type: str | None) -> str
Set default MIME type if not provided.
-#### `set_default_name` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_default_name` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L194" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
set_default_name(self) -> Self
@@ -54,40 +93,78 @@ set_default_name(self) -> Self
Set default name from URI if not provided.
-#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-read(self) -> str | bytes
+read(self) -> str | bytes | ResourceContent
```
Read the resource content.
-This method is not implemented in the base Resource class and must be
-implemented by subclasses.
+This method must be implemented by subclasses. For backwards compatibility,
+subclasses can return str, bytes, or ResourceContent. However, returning
+str or bytes is deprecated - new code should return ResourceContent.
+
+**Returns:**
+- str | bytes | ResourceContent: The resource content. Returning str
+- or bytes is deprecated; prefer ResourceContent for full control
+- over MIME type and metadata.
+
+
+#### `convert_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+convert_result(self, raw_value: Any) -> ResourceContent
+```
+
+Convert a raw return value to ResourceContent.
+
+Handles ResourceContent passthrough and converts raw values using mime_type.
-#### `to_mcp_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `to_mcp_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-to_mcp_resource(self, **overrides: Any) -> MCPResource
+to_mcp_resource(self, **overrides: Any) -> SDKResource
```
-Convert the resource to an MCPResource.
+Convert the resource to an SDKResource.
-#### `key` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L149" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `key` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L286" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
key(self) -> str
```
-The key of the component. This is used for internal bookkeeping
-and may reflect e.g. prefixes or other identifiers. You should not depend on
-keys having a certain value, as the same tool loaded from different
-hierarchies of servers may have different keys.
+The globally unique lookup key for this resource.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this resource with docket for background execution.
+
+#### `add_to_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L296" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, **kwargs: Any) -> Execution
+```
-### `FunctionResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+Schedule this resource for background execution via docket.
+
+**Args:**
+- `docket`: The Docket instance
+- `fn_key`: Function lookup key in Docket registry (defaults to self.key)
+- `task_key`: Redis storage key for the result
+- `**kwargs`: Additional kwargs passed to docket.add()
+
+
+### `FunctionResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
A resource that defers data loading by wrapping a function.
@@ -104,20 +181,37 @@ The function can return:
**Methods:**
-#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L334" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-from_function(cls, fn: Callable[..., Any], uri: str | AnyUrl, name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, mime_type: str | None = None, tags: set[str] | None = None, enabled: bool | None = None, annotations: Annotations | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionResource
+from_function(cls, fn: Callable[..., Any], uri: str | AnyUrl, name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, mime_type: str | None = None, tags: set[str] | None = None, annotations: Annotations | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionResource
```
Create a FunctionResource from a function.
-#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L227" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-read(self) -> str | bytes
+read(self) -> str | bytes | ResourceContent
```
Read the resource by calling the wrapped function.
+**Returns:**
+- str | bytes | ResourceContent: The resource content. If the user's
+- function returns str, bytes, dict, etc., it will be wrapped
+- in ResourceContent. Nested Resource reads may return raw types.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource.py#L400" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this resource with docket for background execution.
+
+FunctionResource registers the underlying function, which has the user's
+Depends parameters for docket to resolve.
+
diff --git a/docs/python-sdk/fastmcp-resources-resource_manager.mdx b/docs/python-sdk/fastmcp-resources-resource_manager.mdx
deleted file mode 100644
index c977132ba..000000000
--- a/docs/python-sdk/fastmcp-resources-resource_manager.mdx
+++ /dev/null
@@ -1,154 +0,0 @@
----
-title: resource_manager
-sidebarTitle: resource_manager
----
-
-# `fastmcp.resources.resource_manager`
-
-
-Resource manager functionality.
-
-## Classes
-
-### `ResourceManager` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource_manager.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-Manages FastMCP resources.
-
-
-**Methods:**
-
-#### `get_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource_manager.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-get_resources(self) -> dict[str, Resource]
-```
-
-Get all registered resources, keyed by URI.
-
-
-#### `get_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource_manager.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-get_resource_templates(self) -> dict[str, ResourceTemplate]
-```
-
-Get all registered templates, keyed by URI template.
-
-
-#### `add_resource_or_template_from_fn` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource_manager.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-add_resource_or_template_from_fn(self, fn: Callable[..., Any], uri: str, name: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None) -> Resource | ResourceTemplate
-```
-
-Add a resource or template to the manager from a function.
-
-**Args:**
-- `fn`: The function to register as a resource or template
-- `uri`: The URI for the resource or template
-- `name`: Optional name for the resource or template
-- `description`: Optional description of the resource or template
-- `mime_type`: Optional MIME type for the resource or template
-- `tags`: Optional set of tags for categorizing the resource or template
-
-**Returns:**
-- The added resource or template. If a resource or template with the same URI already exists,
-- returns the existing resource or template.
-
-
-#### `add_resource_from_fn` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource_manager.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-add_resource_from_fn(self, fn: Callable[..., Any], uri: str, name: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None) -> Resource
-```
-
-Add a resource to the manager from a function.
-
-**Args:**
-- `fn`: The function to register as a resource
-- `uri`: The URI for the resource
-- `name`: Optional name for the resource
-- `description`: Optional description of the resource
-- `mime_type`: Optional MIME type for the resource
-- `tags`: Optional set of tags for categorizing the resource
-
-**Returns:**
-- The added resource. If a resource with the same URI already exists,
-- returns the existing resource.
-
-
-#### `add_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource_manager.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-add_resource(self, resource: Resource) -> Resource
-```
-
-Add a resource to the manager.
-
-**Args:**
-- `resource`: A Resource instance to add. The resource's .key attribute
-will be used as the storage key. To overwrite it, call
-Resource.model_copy(key=new_key) before calling this method.
-
-
-#### `add_template_from_fn` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource_manager.py#L174" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-add_template_from_fn(self, fn: Callable[..., Any], uri_template: str, name: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None) -> ResourceTemplate
-```
-
-Create a template from a function.
-
-
-#### `add_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource_manager.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-add_template(self, template: ResourceTemplate) -> ResourceTemplate
-```
-
-Add a template to the manager.
-
-**Args:**
-- `template`: A ResourceTemplate instance to add. The template's .key attribute
-will be used as the storage key. To overwrite it, call
-ResourceTemplate.model_copy(key=new_key) before calling this method.
-
-**Returns:**
-- The added template. If a template with the same URI already exists,
-- returns the existing template.
-
-
-#### `has_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource_manager.py#L227" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-has_resource(self, uri: AnyUrl | str) -> bool
-```
-
-Check if a resource exists.
-
-
-#### `get_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource_manager.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-get_resource(self, uri: AnyUrl | str) -> Resource
-```
-
-Get resource by URI, checking concrete resources first, then templates.
-
-**Args:**
-- `uri`: The URI of the resource to get
-
-**Raises:**
-- `NotFoundError`: If no resource or template matching the URI is found.
-
-
-#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/resource_manager.py#L289" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-read_resource(self, uri: AnyUrl | str) -> str | bytes
-```
-
-Internal API for servers: Finds and reads a resource, respecting the
-filtered protocol path.
-
diff --git a/docs/python-sdk/fastmcp-resources-template.mdx b/docs/python-sdk/fastmcp-resources-template.mdx
index 1effd3bc6..e01ab0abb 100644
--- a/docs/python-sdk/fastmcp-resources-template.mdx
+++ b/docs/python-sdk/fastmcp-resources-template.mdx
@@ -10,7 +10,7 @@ Resource template functionality.
## Functions
-### `extract_query_params` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `extract_query_params` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
extract_query_params(uri_template: str) -> set[str]
@@ -20,7 +20,7 @@ extract_query_params(uri_template: str) -> set[str]
Extract query parameter names from RFC 6570 `{?param1,param2}` syntax.
-### `build_regex` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `build_regex` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
build_regex(template: str) -> re.Pattern
@@ -35,7 +35,7 @@ Supports:
- `{?var1,var2}` - query parameters (ignored in path matching)
-### `match_uri_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `match_uri_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None
@@ -51,7 +51,7 @@ Supports RFC 6570 URI templates:
## Classes
-### `ResourceTemplate` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ResourceTemplate` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
A template for dynamically creating resources.
@@ -59,25 +59,13 @@ A template for dynamically creating resources.
**Methods:**
-#### `enable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-enable(self) -> None
+from_function(fn: Callable[..., Any], uri_template: str, name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, mime_type: str | None = None, tags: set[str] | None = None, annotations: Annotations | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionResourceTemplate
```
-#### `disable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-disable(self) -> None
-```
-
-#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L128" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-from_function(fn: Callable[..., Any], uri_template: str, name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, mime_type: str | None = None, tags: set[str] | None = None, enabled: bool | None = None, annotations: Annotations | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionResourceTemplate
-```
-
-#### `set_default_mime_type` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_default_mime_type` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
set_default_mime_type(cls, mime_type: str | None) -> str
@@ -86,7 +74,7 @@ set_default_mime_type(cls, mime_type: str | None) -> str
Set default MIME type if not provided.
-#### `matches` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L165" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `matches` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
matches(self, uri: str) -> dict[str, Any] | None
@@ -95,7 +83,7 @@ matches(self, uri: str) -> dict[str, Any] | None
Check if URI matches template and extract parameters.
-#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
read(self, arguments: dict[str, Any]) -> str | bytes
@@ -104,7 +92,18 @@ read(self, arguments: dict[str, Any]) -> str | bytes
Read the resource content.
-#### `create_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L175" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `convert_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+convert_result(self, raw_value: Any) -> ResourceContent
+```
+
+Convert a raw return value to ResourceContent.
+
+Handles ResourceContent passthrough and converts raw values using mime_type.
+
+
+#### `create_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
create_resource(self, uri: str, params: dict[str, Any]) -> Resource
@@ -116,37 +115,59 @@ The base implementation does not support background tasks.
Use FunctionResourceTemplate for task support.
-#### `to_mcp_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L186" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `to_mcp_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L216" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-to_mcp_template(self, **overrides: Any) -> MCPResourceTemplate
+to_mcp_template(self, **overrides: Any) -> SDKResourceTemplate
```
-Convert the resource template to an MCPResourceTemplate.
+Convert the resource template to an SDKResourceTemplate.
-#### `from_mcp_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L208" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `from_mcp_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-from_mcp_template(cls, mcp_template: MCPResourceTemplate) -> ResourceTemplate
+from_mcp_template(cls, mcp_template: SDKResourceTemplate) -> ResourceTemplate
```
Creates a FastMCP ResourceTemplate from a raw MCP ResourceTemplate object.
-#### `key` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `key` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
key(self) -> str
```
-The key of the component. This is used for internal bookkeeping
-and may reflect e.g. prefixes or other identifiers. You should not depend on
-keys having a certain value, as the same tool loaded from different
-hierarchies of servers may have different keys.
+The globally unique lookup key for this template.
-### `FunctionResourceTemplate` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L231" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `register_with_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L255" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this template with docket for background execution.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, params: dict[str, Any], **kwargs: Any) -> Execution
+```
+
+Schedule this template for background execution via docket.
+
+**Args:**
+- `docket`: The Docket instance
+- `params`: Template parameters
+- `fn_key`: Function lookup key in Docket registry (defaults to self.key)
+- `task_key`: Redis storage key for the result
+- `**kwargs`: Additional kwargs passed to docket.add()
+
+
+### `FunctionResourceTemplate` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
A template for dynamically creating resources.
@@ -154,7 +175,7 @@ A template for dynamically creating resources.
**Methods:**
-#### `create_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `create_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L315" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
create_resource(self, uri: str, params: dict[str, Any]) -> Resource
@@ -163,7 +184,7 @@ create_resource(self, uri: str, params: dict[str, Any]) -> Resource
Create a resource from the template with the given parameters.
-#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L333" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
read(self, arguments: dict[str, Any]) -> str | bytes
@@ -172,10 +193,40 @@ read(self, arguments: dict[str, Any]) -> str | bytes
Read the resource content.
-#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L291" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `register_with_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L364" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this template with docket for background execution.
+
+FunctionResourceTemplate registers the underlying function, which has the
+user's Depends parameters for docket to resolve.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, params: dict[str, Any], **kwargs: Any) -> Execution
+```
+
+Schedule this template for background execution via docket.
+
+FunctionResourceTemplate splats the params dict since .fn expects **kwargs.
+
+**Args:**
+- `docket`: The Docket instance
+- `params`: Template parameters
+- `fn_key`: Function lookup key in Docket registry (defaults to self.key)
+- `task_key`: Redis storage key for the result
+- `**kwargs`: Additional kwargs passed to docket.add()
+
+
+#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/template.py#L400" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-from_function(cls, fn: Callable[..., Any], uri_template: str, name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, mime_type: str | None = None, tags: set[str] | None = None, enabled: bool | None = None, annotations: Annotations | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionResourceTemplate
+from_function(cls, fn: Callable[..., Any], uri_template: str, name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, mime_type: str | None = None, tags: set[str] | None = None, annotations: Annotations | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionResourceTemplate
```
Create a template from a function.
diff --git a/docs/python-sdk/fastmcp-resources-types.mdx b/docs/python-sdk/fastmcp-resources-types.mdx
index cebe83516..28cf6ff61 100644
--- a/docs/python-sdk/fastmcp-resources-types.mdx
+++ b/docs/python-sdk/fastmcp-resources-types.mdx
@@ -21,7 +21,7 @@ A resource that reads from a string.
#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-read(self) -> str
+read(self) -> ResourceContent
```
Read the text content.
@@ -38,7 +38,7 @@ A resource that reads from bytes.
#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-read(self) -> bytes
+read(self) -> ResourceContent
```
Read the binary content.
@@ -75,13 +75,13 @@ Set is_binary based on mime_type if not explicitly set.
#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-read(self) -> str | bytes
+read(self) -> ResourceContent
```
Read the file content.
-### `HttpResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `HttpResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
A resource that reads from an HTTP endpoint.
@@ -89,16 +89,16 @@ A resource that reads from an HTTP endpoint.
**Methods:**
-#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-read(self) -> str | bytes
+read(self) -> ResourceContent
```
Read the HTTP content.
-### `DirectoryResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `DirectoryResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
A resource that lists files in a directory.
@@ -106,7 +106,7 @@ A resource that lists files in a directory.
**Methods:**
-#### `validate_absolute_path` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `validate_absolute_path` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L128" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
validate_absolute_path(cls, path: Path) -> Path
@@ -115,7 +115,7 @@ validate_absolute_path(cls, path: Path) -> Path
Ensure path is absolute.
-#### `list_files` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_files` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L134" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_files(self) -> list[Path]
@@ -124,10 +124,10 @@ list_files(self) -> list[Path]
List files in the directory.
-#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-read(self) -> str
+read(self) -> ResourceContent
```
Read the directory listing.
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx b/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx
index 69d85f724..56d2527ef 100644
--- a/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx
+++ b/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx
@@ -72,7 +72,7 @@ Features:
**Methods:**
-#### `get_token_verifier` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/providers/aws.py#L241" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_token_verifier` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/providers/aws.py#L245" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_token_verifier(self) -> TokenVerifier
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx b/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx
index 5fb265b32..686052344 100644
--- a/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx
+++ b/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx
@@ -55,7 +55,7 @@ Setup:
**Methods:**
-#### `authorize` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/providers/azure.py#L312" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `authorize` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/providers/azure.py#L317" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
authorize(self, client: OAuthClientInformationFull, params: AuthorizationParams) -> str
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx b/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx
index a2ec529ad..b91f02263 100644
--- a/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx
+++ b/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx
@@ -65,9 +65,9 @@ Setup Requirements:
4. Note your Client ID and Client Secret
-### `AuthKitProviderSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `AuthKitProviderSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-### `AuthKitProvider` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L300" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `AuthKitProvider` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L304" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
AuthKit metadata provider for DCR (Dynamic Client Registration).
@@ -93,7 +93,7 @@ https://workos.com/docs/authkit/mcp/integrating/token-verification
**Methods:**
-#### `get_routes` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L383" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_routes` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L387" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_routes(self, mcp_path: str | None = None) -> list[Route]
diff --git a/docs/python-sdk/fastmcp-server-context.mdx b/docs/python-sdk/fastmcp-server-context.mdx
index fa3a35f2f..112c89c70 100644
--- a/docs/python-sdk/fastmcp-server-context.mdx
+++ b/docs/python-sdk/fastmcp-server-context.mdx
@@ -7,7 +7,7 @@ sidebarTitle: context
## Functions
-### `set_context` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `set_context` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
set_context(context: Context) -> Generator[Context, None, None]
@@ -15,7 +15,7 @@ set_context(context: Context) -> Generator[Context, None, None]
## Classes
-### `LogData` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `LogData` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Data object for passing log arguments to client-side handlers.
@@ -24,7 +24,7 @@ This provides an interface to match the Python standard library logging,
for compatibility with structured logging.
-### `Context` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `Context` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L115" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Context object providing access to MCP capabilities.
@@ -72,7 +72,7 @@ The context is optional - tools that don't need it can omit the parameter.
**Methods:**
-#### `fastmcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `fastmcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
fastmcp(self) -> FastMCP
@@ -81,7 +81,7 @@ fastmcp(self) -> FastMCP
Get the FastMCP instance.
-#### `request_context` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L193" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `request_context` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
request_context(self) -> RequestContext[ServerSession, Any, Request] | None
@@ -110,7 +110,7 @@ async def on_request(self, context, call_next):
```
-#### `report_progress` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `report_progress` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
report_progress(self, progress: float, total: float | None = None, message: str | None = None) -> None
@@ -123,10 +123,10 @@ Report progress for the current operation.
- `total`: Optional total value e.g. 100
-#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L248" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L278" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-list_resources(self) -> list[MCPResource]
+list_resources(self) -> list[SDKResource]
```
List all available resources from the server.
@@ -135,10 +135,10 @@ List all available resources from the server.
- List of Resource objects available on the server
-#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L256" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L286" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-list_prompts(self) -> list[MCPPrompt]
+list_prompts(self) -> list[SDKPrompt]
```
List all available prompts from the server.
@@ -147,7 +147,7 @@ List all available prompts from the server.
- List of Prompt objects available on the server
-#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L264" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L294" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> GetPromptResult
@@ -163,10 +163,10 @@ Get a prompt by name with optional arguments.
- The prompt result
-#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L278" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L308" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-read_resource(self, uri: str | AnyUrl) -> list[ReadResourceContents]
+read_resource(self, uri: str | AnyUrl) -> list[ResourceContent]
```
Read a resource by URI.
@@ -175,10 +175,10 @@ Read a resource by URI.
- `uri`: Resource URI to read
**Returns:**
-- The resource content as either text or bytes
+- List of ResourceContent objects
-#### `log` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `log` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L320" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
log(self, message: str, level: LoggingLevel | None = None, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
@@ -196,7 +196,7 @@ Messages sent to Clients are also logged to the `fastmcp.server.context.to_clien
- `extra`: Optional mapping for additional arguments
-#### `client_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L319" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `client_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L349" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
client_id(self) -> str | None
@@ -205,7 +205,7 @@ client_id(self) -> str | None
Get the client ID if available.
-#### `request_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L328" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `request_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
request_id(self) -> str
@@ -216,7 +216,7 @@ Get the unique ID for this request.
Raises RuntimeError if MCP request context is not available.
-#### `session_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L341" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `session_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L371" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
session_id(self) -> str
@@ -233,7 +233,7 @@ the same client session.
- for other transports.
-#### `session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L423" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
session(self) -> ServerSession
@@ -244,7 +244,7 @@ Access to the underlying session for advanced usage.
Raises RuntimeError if MCP request context is not available.
-#### `debug` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L406" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `debug` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L436" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
debug(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
@@ -255,7 +255,7 @@ Send a `DEBUG`-level message to the connected MCP Client.
Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`.
-#### `info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L422" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L452" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
info(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
@@ -266,7 +266,7 @@ Send a `INFO`-level message to the connected MCP Client.
Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`.
-#### `warning` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L438" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `warning` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L468" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
warning(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
@@ -277,7 +277,7 @@ Send a `WARNING`-level message to the connected MCP Client.
Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`.
-#### `error` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L454" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `error` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L484" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
error(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
@@ -288,7 +288,7 @@ Send a `ERROR`-level message to the connected MCP Client.
Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`.
-#### `list_roots` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L470" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_roots` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L500" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_roots(self) -> list[Root]
@@ -297,34 +297,38 @@ list_roots(self) -> list[Root]
List the roots available to the server, as indicated by the client.
-#### `send_tool_list_changed` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L475" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `send_notification` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L505" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-send_tool_list_changed(self) -> None
+send_notification(self, notification: mcp.types.ServerNotificationType) -> None
```
-Send a tool list changed notification to the client.
+Send a notification to the client immediately.
+Use this in async code when you want the notification sent right away.
+For sync code, use send_notification_sync() which queues the notification
+for the background flusher.
-#### `send_resource_list_changed` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L479" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-send_resource_list_changed(self) -> None
-```
-
-Send a resource list changed notification to the client.
+**Args:**
+- `notification`: An MCP notification instance (e.g., ToolListChangedNotification())
-#### `send_prompt_list_changed` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L483" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `send_notification_sync` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L519" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-send_prompt_list_changed(self) -> None
+send_notification_sync(self, notification: mcp.types.ServerNotificationType) -> None
```
-Send a prompt list changed notification to the client.
+Queue a notification to be sent by the background flusher.
+
+Use this in sync code when you can't await. The notification will be
+sent within ~1 second by the background flusher.
+**Args:**
+- `notification`: An MCP notification instance (e.g., ToolListChangedNotification())
-#### `close_sse_stream` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L487" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+#### `close_sse_stream` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L532" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
close_sse_stream(self) -> None
@@ -342,41 +346,143 @@ Instead of holding a connection open for minutes, you can periodically close
and let the client reconnect.
-#### `sample` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L526" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `sample_step` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L571" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+sample_step(self, messages: str | Sequence[str | SamplingMessage]) -> SampleStep
+```
+
+Make a single LLM sampling call.
+
+This is a stateless function that makes exactly one LLM call and optionally
+executes any requested tools. Use this for fine-grained control over the
+sampling loop.
+
+**Args:**
+- `messages`: The message(s) to send. Can be a string, list of strings,
+or list of SamplingMessage objects.
+- `system_prompt`: Optional system prompt for the LLM.
+- `temperature`: Optional sampling temperature.
+- `max_tokens`: Maximum tokens to generate. Defaults to 512.
+- `model_preferences`: Optional model preferences.
+- `tools`: Optional list of tools the LLM can use.
+- `tool_choice`: Tool choice mode ("auto", "required", or "none").
+- `execute_tools`: If True (default), execute tool calls and append results
+to history. If False, return immediately with tool_calls available
+in the step for manual execution.
+- `mask_error_details`: If True, mask detailed error messages from tool
+execution. When None (default), uses the global settings value.
+Tools can raise ToolError to bypass masking.
+
+**Returns:**
+- SampleStep containing:
+- - .response: The raw LLM response
+- - .history: Messages including input, assistant response, and tool results
+- - .is_tool_use: True if the LLM requested tool execution
+- - .tool_calls: List of tool calls (if any)
+- - .text: The text content (if any)
+
+
+#### `sample` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L724" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[ResultT]
+```
+
+Overload: With result_type, returns SamplingResult[ResultT].
+
+
+#### `sample` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L739" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-sample(self, messages: str | Sequence[str | SamplingMessage], system_prompt: str | None = None, include_context: IncludeContext | None = None, temperature: float | None = None, max_tokens: int | None = None, model_preferences: ModelPreferences | str | list[str] | None = None) -> SamplingMessageContentBlock | list[SamplingMessageContentBlock]
+sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[str]
+```
+
+Overload: Without result_type, returns SamplingResult[str].
+
+
+#### `sample` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L753" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[ResultT] | SamplingResult[str]
```
Send a sampling request to the client and await the response.
-Call this method at any time to have the server request an LLM
-completion from the client. The client must be appropriately configured,
-or the request will error.
+This method runs to completion automatically. When tools are provided,
+it executes a tool loop: if the LLM returns a tool use request, the tools
+are executed and the results are sent back to the LLM. This continues
+until the LLM provides a final text response.
+
+When result_type is specified, a synthetic `final_response` tool is
+created. The LLM calls this tool to provide the structured response,
+which is validated against the result_type and returned as `.result`.
+
+For fine-grained control over the sampling loop, use sample_step() instead.
+
+**Args:**
+- `messages`: The message(s) to send. Can be a string, list of strings,
+or list of SamplingMessage objects.
+- `system_prompt`: Optional system prompt for the LLM.
+- `temperature`: Optional sampling temperature.
+- `max_tokens`: Maximum tokens to generate. Defaults to 512.
+- `model_preferences`: Optional model preferences.
+- `tools`: Optional list of tools the LLM can use. Accepts plain
+functions or SamplingTools.
+- `result_type`: Optional type for structured output. When specified,
+a synthetic `final_response` tool is created and the LLM's
+response is validated against this type.
+- `mask_error_details`: If True, mask detailed error messages from tool
+execution. When None (default), uses the global settings value.
+Tools can raise ToolError to bypass masking.
+
+**Returns:**
+- SamplingResult[T] containing:
+- - .text: The text representation (raw text or JSON for structured)
+- - .result: The typed result (str for text, parsed object for structured)
+- - .history: All messages exchanged during sampling
-#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L610" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L910" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
elicit(self, message: str, response_type: None) -> AcceptedElicitation[dict[str, Any]] | DeclinedElicitation | CancelledElicitation
```
-#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L622" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L922" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
elicit(self, message: str, response_type: type[T]) -> AcceptedElicitation[T] | DeclinedElicitation | CancelledElicitation
```
-#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L632" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L932" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
elicit(self, message: str, response_type: list[str]) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation
```
-#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L641" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L942" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+elicit(self, message: str, response_type: dict[str, dict[str, str]]) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation
+```
+
+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L952" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+elicit(self, message: str, response_type: list[list[str]]) -> AcceptedElicitation[list[str]] | DeclinedElicitation | CancelledElicitation
+```
+
+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L964" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+elicit(self, message: str, response_type: list[dict[str, dict[str, str]]]) -> AcceptedElicitation[list[str]] | DeclinedElicitation | CancelledElicitation
+```
+
+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L976" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-elicit(self, message: str, response_type: type[T] | list[str] | None = None) -> AcceptedElicitation[T] | AcceptedElicitation[dict[str, Any]] | AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation
+elicit(self, message: str, response_type: type[T] | list[str] | dict[str, dict[str, str]] | list[list[str]] | list[dict[str, dict[str, str]]] | None = None) -> AcceptedElicitation[T] | AcceptedElicitation[dict[str, Any]] | AcceptedElicitation[str] | AcceptedElicitation[list[str]] | DeclinedElicitation | CancelledElicitation
```
Send an elicitation request to the client and await the response.
@@ -402,7 +508,7 @@ type or dataclass or BaseModel. If it is a primitive type, an
object schema with a single "value" field will be generated.
-#### `set_state` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L692" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_state` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1033" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
set_state(self, key: str, value: Any) -> None
@@ -411,7 +517,7 @@ set_state(self, key: str, value: Any) -> None
Set a value in the context state.
-#### `get_state` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L696" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_state` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1037" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_state(self, key: str) -> Any
diff --git a/docs/python-sdk/fastmcp-server-dependencies.mdx b/docs/python-sdk/fastmcp-server-dependencies.mdx
index 19636c2ce..6c7478ccd 100644
--- a/docs/python-sdk/fastmcp-server-dependencies.mdx
+++ b/docs/python-sdk/fastmcp-server-dependencies.mdx
@@ -7,7 +7,7 @@ sidebarTitle: dependencies
## Functions
-### `without_injected_parameters` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `without_injected_parameters` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
without_injected_parameters(fn: Callable[..., Any]) -> Callable[..., Any]
@@ -28,7 +28,7 @@ Context injection when called.
- Async wrapper function without injected parameters
-### `resolve_dependencies` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L208" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `resolve_dependencies` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L224" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
resolve_dependencies(fn: Callable[..., Any], arguments: dict[str, Any]) -> AsyncGenerator[dict[str, Any], None]
@@ -52,13 +52,27 @@ providing values for dependency parameter names. This is a security feature.
which will be filtered out)
-### `get_context` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L255" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `get_context` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L271" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_context() -> Context
```
-### `CurrentContext` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L271" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `get_task_metadata` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L280" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_task_metadata() -> dict[str, Any] | None
+```
+
+
+Get the current task metadata from the context.
+
+**Returns:**
+- The task metadata dict if this is a background task request,
+- or None if this is a normal execution.
+
+
+### `CurrentContext` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
CurrentContext() -> Context
@@ -77,7 +91,7 @@ current MCP operation (tool/resource/prompt call).
- `RuntimeError`: If no active context found (during resolution)
-### `CurrentDocket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `CurrentDocket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L337" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
CurrentDocket() -> Docket
@@ -96,7 +110,7 @@ automatically creates for background task scheduling.
- `RuntimeError`: If not within a FastMCP server context
-### `CurrentWorker` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `CurrentWorker` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L376" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
CurrentWorker() -> Worker
@@ -115,7 +129,7 @@ automatically creates for background task processing.
- `RuntimeError`: If not within a FastMCP server context
-### `CurrentFastMCP` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L463" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `CurrentFastMCP` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L489" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
CurrentFastMCP()
@@ -133,7 +147,7 @@ This dependency provides access to the active FastMCP server.
- `RuntimeError`: If no server in context (during resolution)
-### `get_server` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L488" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `get_server` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L514" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_server()
@@ -149,13 +163,13 @@ Get the current FastMCP server instance directly.
- `RuntimeError`: If no server in context
-### `get_http_request` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L507" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `get_http_request` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L533" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_http_request() -> Request
```
-### `get_http_headers` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L523" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `get_http_headers` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L549" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_http_headers(include_all: bool = False) -> dict[str, str]
@@ -171,7 +185,7 @@ By default, strips problematic headers like `content-length` that cause issues i
If `include_all` is True, all headers are returned.
-### `get_access_token` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L569" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `get_access_token` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L595" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_access_token() -> AccessToken | None
@@ -191,7 +205,7 @@ request is available.
## Classes
-### `InMemoryProgress` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `InMemoryProgress` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L400" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
In-memory progress tracker for immediate tool execution.
@@ -203,25 +217,25 @@ progress doesn't need to be observable across processes.
**Methods:**
-#### `current` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L392" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `current` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L418" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
current(self) -> int | None
```
-#### `total` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `total` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L422" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
total(self) -> int
```
-#### `message` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L400" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `message` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L426" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
message(self) -> str | None
```
-#### `set_total` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L403" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_total` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L429" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
set_total(self, total: int) -> None
@@ -230,7 +244,7 @@ set_total(self, total: int) -> None
Set the total/target value for progress tracking.
-#### `increment` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L409" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `increment` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
increment(self, amount: int = 1) -> None
@@ -239,7 +253,7 @@ increment(self, amount: int = 1) -> None
Atomically increment the current progress value.
-#### `set_message` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L418" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_message` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L444" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
set_message(self, message: str | None) -> None
@@ -248,7 +262,7 @@ set_message(self, message: str | None) -> None
Update the progress status message.
-### `Progress` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L423" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `Progress` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L449" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
FastMCP Progress dependency that works in both server and worker contexts.
diff --git a/docs/python-sdk/fastmcp-server-elicitation.mdx b/docs/python-sdk/fastmcp-server-elicitation.mdx
index 04a9be73a..109181232 100644
--- a/docs/python-sdk/fastmcp-server-elicitation.mdx
+++ b/docs/python-sdk/fastmcp-server-elicitation.mdx
@@ -138,3 +138,8 @@ Result when user accepts the elicitation.
Configuration for an elicitation request.
+**Attributes:**
+- `schema`: The JSON schema to send to the client
+- `response_type`: The type to validate responses with (None for raw schemas)
+- `is_raw`: True if schema was built directly (extract "value" from response)
+
diff --git a/docs/python-sdk/fastmcp-server-middleware-caching.mdx b/docs/python-sdk/fastmcp-server-middleware-caching.mdx
index 929203e2f..58b15ce60 100644
--- a/docs/python-sdk/fastmcp-server-middleware-caching.mdx
+++ b/docs/python-sdk/fastmcp-server-middleware-caching.mdx
@@ -10,10 +10,10 @@ A middleware for response caching.
## Classes
-### `CachableReadResourceContents` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `CachableReadResourceContents` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-A wrapper for ReadResourceContents that can be cached.
+A wrapper for ResourceContent that can be cached.
**Methods:**
@@ -33,76 +33,76 @@ get_sizes(cls, values: Sequence[Self]) -> int
#### `wrap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-wrap(cls, values: Sequence[ReadResourceContents]) -> list[Self]
+wrap(cls, values: Sequence[ResourceContent]) -> list[Self]
```
-#### `unwrap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `unwrap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-unwrap(cls, values: Sequence[Self]) -> list[ReadResourceContents]
+unwrap(cls, values: Sequence[Self]) -> list[ResourceContent]
```
-### `CachableToolResult` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `CachableToolResult` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
**Methods:**
-#### `wrap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `wrap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
wrap(cls, value: ToolResult) -> Self
```
-#### `unwrap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `unwrap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
unwrap(self) -> ToolResult
```
-### `SharedMethodSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `SharedMethodSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Shared config for a cache method.
-### `ListToolsSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ListToolsSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Configuration options for Tool-related caching.
-### `ListResourcesSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ListResourcesSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Configuration options for Resource-related caching.
-### `ListPromptsSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ListPromptsSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Configuration options for Prompt-related caching.
-### `CallToolSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `CallToolSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Configuration options for Tool-related caching.
-### `ReadResourceSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ReadResourceSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L115" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Configuration options for Resource-related caching.
-### `GetPromptSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `GetPromptSettings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Configuration options for Prompt-related caching.
-### `ResponseCachingStatistics` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ResponseCachingStatistics` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-### `ResponseCachingMiddleware` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ResponseCachingMiddleware` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
The response caching middleware offers a simple way to cache responses to mcp methods. The Middleware
@@ -119,7 +119,7 @@ Notes:
**Methods:**
-#### `on_list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L233" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_list_tools(self, context: MiddlewareContext[mcp.types.ListToolsRequest], call_next: CallNext[mcp.types.ListToolsRequest, Sequence[Tool]]) -> Sequence[Tool]
@@ -129,7 +129,7 @@ List tools from the cache, if caching is enabled, and the result is in the cache
otherwise call the next middleware and store the result in the cache if caching is enabled.
-#### `on_list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L273" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L277" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_list_resources(self, context: MiddlewareContext[mcp.types.ListResourcesRequest], call_next: CallNext[mcp.types.ListResourcesRequest, Sequence[Resource]]) -> Sequence[Resource]
@@ -139,7 +139,7 @@ List resources from the cache, if caching is enabled, and the result is in the c
otherwise call the next middleware and store the result in the cache if caching is enabled.
-#### `on_list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L313" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L316" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_list_prompts(self, context: MiddlewareContext[mcp.types.ListPromptsRequest], call_next: CallNext[mcp.types.ListPromptsRequest, Sequence[Prompt]]) -> Sequence[Prompt]
@@ -149,7 +149,7 @@ List prompts from the cache, if caching is enabled, and the result is in the cac
otherwise call the next middleware and store the result in the cache if caching is enabled.
-#### `on_call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L351" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L353" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_call_tool(self, context: MiddlewareContext[mcp.types.CallToolRequestParams], call_next: CallNext[mcp.types.CallToolRequestParams, ToolResult]) -> ToolResult
@@ -159,20 +159,20 @@ Call a tool from the cache, if caching is enabled, and the result is in the cach
otherwise call the next middleware and store the result in the cache if caching is enabled.
-#### `on_read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L384" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L386" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-on_read_resource(self, context: MiddlewareContext[mcp.types.ReadResourceRequestParams], call_next: CallNext[mcp.types.ReadResourceRequestParams, Sequence[ReadResourceContents]]) -> Sequence[ReadResourceContents]
+on_read_resource(self, context: MiddlewareContext[mcp.types.ReadResourceRequestParams], call_next: CallNext[mcp.types.ReadResourceRequestParams, Sequence[ResourceContent]]) -> Sequence[ResourceContent]
```
Read a resource from the cache, if caching is enabled, and the result is in the cache. Otherwise,
otherwise call the next middleware and store the result in the cache if caching is enabled.
-#### `on_get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L414" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L416" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-on_get_prompt(self, context: MiddlewareContext[mcp.types.GetPromptRequestParams], call_next: CallNext[mcp.types.GetPromptRequestParams, mcp.types.GetPromptResult]) -> mcp.types.GetPromptResult
+on_get_prompt(self, context: MiddlewareContext[mcp.types.GetPromptRequestParams], call_next: CallNext[mcp.types.GetPromptRequestParams, PromptResult]) -> PromptResult
```
Get a prompt from the cache, if caching is enabled, and the result is in the cache. Otherwise,
diff --git a/docs/python-sdk/fastmcp-server-middleware-middleware.mdx b/docs/python-sdk/fastmcp-server-middleware-middleware.mdx
index baeffa691..9f5f8fd0f 100644
--- a/docs/python-sdk/fastmcp-server-middleware-middleware.mdx
+++ b/docs/python-sdk/fastmcp-server-middleware-middleware.mdx
@@ -7,7 +7,7 @@ sidebarTitle: middleware
## Functions
-### `make_middleware_wrapper` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `make_middleware_wrapper` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
make_middleware_wrapper(middleware: Middleware, call_next: CallNext[T, R]) -> CallNext[T, R]
@@ -21,9 +21,9 @@ passed to other functions that expect a call_next function.
## Classes
-### `CallNext` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `CallNext` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-### `MiddlewareContext` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `MiddlewareContext` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Unified context for all middleware operations.
@@ -31,13 +31,13 @@ Unified context for all middleware operations.
**Methods:**
-#### `copy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `copy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
copy(self, **kwargs: Any) -> MiddlewareContext[T]
```
-### `Middleware` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `Middleware` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Base class for FastMCP middleware with dispatching hooks.
@@ -45,67 +45,67 @@ Base class for FastMCP middleware with dispatching hooks.
**Methods:**
-#### `on_message` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_message` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L128" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_message(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) -> Any
```
-#### `on_request` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_request` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_request(self, context: MiddlewareContext[mt.Request[Any, Any]], call_next: CallNext[mt.Request[Any, Any], Any]) -> Any
```
-#### `on_notification` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_notification` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_notification(self, context: MiddlewareContext[mt.Notification[Any, Any]], call_next: CallNext[mt.Notification[Any, Any], Any]) -> Any
```
-#### `on_initialize` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_initialize` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L149" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_initialize(self, context: MiddlewareContext[mt.InitializeRequest], call_next: CallNext[mt.InitializeRequest, mt.InitializeResult | None]) -> mt.InitializeResult | None
```
-#### `on_call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_call_tool(self, context: MiddlewareContext[mt.CallToolRequestParams], call_next: CallNext[mt.CallToolRequestParams, ToolResult]) -> ToolResult
```
-#### `on_read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-on_read_resource(self, context: MiddlewareContext[mt.ReadResourceRequestParams], call_next: CallNext[mt.ReadResourceRequestParams, Sequence[ReadResourceContents]]) -> Sequence[ReadResourceContents]
+on_read_resource(self, context: MiddlewareContext[mt.ReadResourceRequestParams], call_next: CallNext[mt.ReadResourceRequestParams, Sequence[ResourceContent]]) -> Sequence[ResourceContent]
```
-#### `on_get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L170" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-on_get_prompt(self, context: MiddlewareContext[mt.GetPromptRequestParams], call_next: CallNext[mt.GetPromptRequestParams, mt.GetPromptResult]) -> mt.GetPromptResult
+on_get_prompt(self, context: MiddlewareContext[mt.GetPromptRequestParams], call_next: CallNext[mt.GetPromptRequestParams, PromptResult]) -> PromptResult
```
-#### `on_list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_list_tools(self, context: MiddlewareContext[mt.ListToolsRequest], call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]]) -> Sequence[Tool]
```
-#### `on_list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_list_resources(self, context: MiddlewareContext[mt.ListResourcesRequest], call_next: CallNext[mt.ListResourcesRequest, Sequence[Resource]]) -> Sequence[Resource]
```
-#### `on_list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L194" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_list_resource_templates(self, context: MiddlewareContext[mt.ListResourceTemplatesRequest], call_next: CallNext[mt.ListResourceTemplatesRequest, Sequence[ResourceTemplate]]) -> Sequence[ResourceTemplate]
```
-#### `on_list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L203" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `on_list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
on_list_prompts(self, context: MiddlewareContext[mt.ListPromptsRequest], call_next: CallNext[mt.ListPromptsRequest, Sequence[Prompt]]) -> Sequence[Prompt]
diff --git a/docs/python-sdk/fastmcp-server-middleware-tool_injection.mdx b/docs/python-sdk/fastmcp-server-middleware-tool_injection.mdx
index 946a5f33a..9e2c663c1 100644
--- a/docs/python-sdk/fastmcp-server-middleware-tool_injection.mdx
+++ b/docs/python-sdk/fastmcp-server-middleware-tool_injection.mdx
@@ -43,7 +43,7 @@ List resources available on the server.
### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/middleware/tool_injection.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-read_resource(context: Context, uri: Annotated[AnyUrl | str, 'The URI of the resource to read.']) -> list[ReadResourceContents]
+read_resource(context: Context, uri: Annotated[AnyUrl | str, 'The URI of the resource to read.']) -> list[ResourceContent]
```
diff --git a/docs/python-sdk/fastmcp-server-openapi-__init__.mdx b/docs/python-sdk/fastmcp-server-openapi-__init__.mdx
index 2e2cfe6e2..af9cd5517 100644
--- a/docs/python-sdk/fastmcp-server-openapi-__init__.mdx
+++ b/docs/python-sdk/fastmcp-server-openapi-__init__.mdx
@@ -6,4 +6,22 @@ sidebarTitle: __init__
# `fastmcp.server.openapi`
-OpenAPI server implementation for FastMCP - refactored for better maintainability.
+OpenAPI server implementation for FastMCP.
+
+.. deprecated::
+ This module is deprecated. Import from fastmcp.server.providers.openapi instead.
+
+The recommended approach is to use OpenAPIProvider with FastMCP:
+
+ from fastmcp import FastMCP
+ from fastmcp.server.providers.openapi import OpenAPIProvider
+ import httpx
+
+ client = httpx.AsyncClient(base_url="https://api.example.com")
+ provider = OpenAPIProvider(openapi_spec=spec, client=client)
+
+ mcp = FastMCP("My API Server")
+ mcp.add_provider(provider)
+
+FastMCPOpenAPI is still available but deprecated.
+
diff --git a/docs/python-sdk/fastmcp-server-openapi-components.mdx b/docs/python-sdk/fastmcp-server-openapi-components.mdx
index 4a12d363f..320cc7092 100644
--- a/docs/python-sdk/fastmcp-server-openapi-components.mdx
+++ b/docs/python-sdk/fastmcp-server-openapi-components.mdx
@@ -6,57 +6,7 @@ sidebarTitle: components
# `fastmcp.server.openapi.components`
-OpenAPI component implementations: Tool, Resource, and ResourceTemplate classes.
+OpenAPI component implementations - backwards compatibility stub.
-## Classes
-
-### `OpenAPITool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/openapi/components.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-Tool implementation for OpenAPI endpoints.
-
-
-**Methods:**
-
-#### `run` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/openapi/components.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-run(self, arguments: dict[str, Any]) -> ToolResult
-```
-
-Execute the HTTP request using RequestDirector for simplified parameter handling.
-
-
-### `OpenAPIResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/openapi/components.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-Resource implementation for OpenAPI endpoints.
-
-
-**Methods:**
-
-#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/openapi/components.py#L190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-read(self) -> str | bytes
-```
-
-Fetch the resource data by making an HTTP request.
-
-
-### `OpenAPIResourceTemplate` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/openapi/components.py#L289" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-Resource template implementation for OpenAPI endpoints.
-
-
-**Methods:**
-
-#### `create_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/openapi/components.py#L322" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-create_resource(self, uri: str, params: dict[str, Any], context: 'Context | None' = None) -> Resource
-```
-
-Create a resource with the given parameters.
+This module is deprecated. Import from fastmcp.server.providers.openapi instead.
diff --git a/docs/python-sdk/fastmcp-server-openapi-routing.mdx b/docs/python-sdk/fastmcp-server-openapi-routing.mdx
index cbe4b7ce1..650a4a497 100644
--- a/docs/python-sdk/fastmcp-server-openapi-routing.mdx
+++ b/docs/python-sdk/fastmcp-server-openapi-routing.mdx
@@ -8,16 +8,6 @@ sidebarTitle: routing
Route mapping logic for OpenAPI operations.
-## Classes
-
-### `MCPType` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/openapi/routing.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-Type of FastMCP component to create from a route.
-
-
-### `RouteMap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/openapi/routing.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-Mapping configuration for HTTP routes to FastMCP component types.
+.. deprecated::
+ This module is deprecated. Import from fastmcp.server.providers.openapi instead.
diff --git a/docs/python-sdk/fastmcp-server-openapi-server.mdx b/docs/python-sdk/fastmcp-server-openapi-server.mdx
index 77a452f9f..2cae5e9af 100644
--- a/docs/python-sdk/fastmcp-server-openapi-server.mdx
+++ b/docs/python-sdk/fastmcp-server-openapi-server.mdx
@@ -6,15 +6,38 @@ sidebarTitle: server
# `fastmcp.server.openapi.server`
-FastMCP server implementation for OpenAPI integration.
+FastMCPOpenAPI - backwards compatibility wrapper.
+
+This class is deprecated. Use FastMCP with OpenAPIProvider instead:
+
+ from fastmcp import FastMCP
+ from fastmcp.server.providers.openapi import OpenAPIProvider
+ import httpx
+
+ client = httpx.AsyncClient(base_url="https://api.example.com")
+ provider = OpenAPIProvider(openapi_spec=spec, client=client)
+ mcp = FastMCP("My API Server", providers=[provider])
+
## Classes
-### `FastMCPOpenAPI` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/openapi/server.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `FastMCPOpenAPI` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/openapi/server.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
FastMCP server implementation that creates components from an OpenAPI schema.
-This class parses an OpenAPI specification and creates appropriate FastMCP components
-(Tools, Resources, ResourceTemplates) based on route mappings.
+.. deprecated::
+ Use FastMCP with OpenAPIProvider instead. This class will be
+ removed in a future version.
+
+Example (deprecated):
+ ```python
+ from fastmcp.server.openapi import FastMCPOpenAPI
+ import httpx
+
+ server = FastMCPOpenAPI(
+ openapi_spec=spec,
+ client=httpx.AsyncClient(),
+ )
+ ```
diff --git a/docs/python-sdk/fastmcp-server-providers-__init__.mdx b/docs/python-sdk/fastmcp-server-providers-__init__.mdx
new file mode 100644
index 000000000..277e67e60
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-__init__.mdx
@@ -0,0 +1,34 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.providers`
+
+
+Providers for dynamic MCP components.
+
+This module provides the `Provider` abstraction for providing tools,
+resources, and prompts dynamically at runtime.
+
+Example:
+ ```python
+ from fastmcp import FastMCP
+ from fastmcp.server.providers import Provider
+ from fastmcp.tools import Tool
+
+ class DatabaseProvider(Provider):
+ def __init__(self, db_url: str):
+ self.db = Database(db_url)
+
+ async def list_tools(self) -> list[Tool]:
+ rows = await self.db.fetch("SELECT * FROM tools")
+ return [self._make_tool(row) for row in rows]
+
+ async def get_tool(self, name: str) -> Tool | None:
+ row = await self.db.fetchone("SELECT * FROM tools WHERE name = ?", name)
+ return self._make_tool(row) if row else None
+
+ mcp = FastMCP("Server", providers=[DatabaseProvider(db_url)])
+ ```
+
diff --git a/docs/python-sdk/fastmcp-server-providers-base.mdx b/docs/python-sdk/fastmcp-server-providers-base.mdx
new file mode 100644
index 000000000..d7af88d69
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-base.mdx
@@ -0,0 +1,264 @@
+---
+title: base
+sidebarTitle: base
+---
+
+# `fastmcp.server.providers.base`
+
+
+Base Provider class for dynamic MCP components.
+
+This module provides the `Provider` abstraction for providing tools,
+resources, and prompts dynamically at runtime.
+
+Example:
+ ```python
+ from fastmcp import FastMCP
+ from fastmcp.server.providers import Provider
+ from fastmcp.tools import Tool
+
+ class DatabaseProvider(Provider):
+ def __init__(self, db_url: str):
+ super().__init__()
+ self.db = Database(db_url)
+
+ async def list_tools(self) -> list[Tool]:
+ rows = await self.db.fetch("SELECT * FROM tools")
+ return [self._make_tool(row) for row in rows]
+
+ async def get_tool(self, name: str) -> Tool | None:
+ row = await self.db.fetchone("SELECT * FROM tools WHERE name = ?", name)
+ return self._make_tool(row) if row else None
+
+ mcp = FastMCP("Server", providers=[DatabaseProvider(db_url)])
+ ```
+
+
+## Classes
+
+### `Provider` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Base class for dynamic component providers.
+
+Subclass and override whichever methods you need. Default implementations
+return empty lists / None, so you only need to implement what your provider
+supports.
+
+
+**Methods:**
+
+#### `with_transforms` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+with_transforms(self) -> Provider
+```
+
+Apply transformations to this provider's components.
+
+Returns a TransformingProvider that wraps this provider and applies
+the specified transformations. Can be chained - each call creates a
+new wrapper that composes with the previous.
+
+**Args:**
+- `namespace`: Prefix for tools/prompts ("namespace_name"), path segment
+for resources ("protocol\://namespace/path").
+- `tool_renames`: Map of original_name β†’ final_name. Tools in this map
+use the specified name instead of namespace prefixing.
+
+**Returns:**
+- A TransformingProvider wrapping this provider.
+
+
+#### `with_namespace` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+with_namespace(self, namespace: str) -> Provider
+```
+
+Shorthand for with_transforms(namespace=...).
+
+**Args:**
+- `namespace`: The namespace to apply.
+
+**Returns:**
+- A TransformingProvider wrapping this provider.
+
+
+#### `list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L131" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self) -> Sequence[Tool]
+```
+
+Return all available tools.
+
+Override to provide tools dynamically.
+
+
+#### `get_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str) -> Tool | None
+```
+
+Get a specific tool by name.
+
+Default implementation lists all tools and finds by name.
+Override for more efficient single-tool lookup.
+
+**Returns:**
+- The Tool if found, or None to continue searching other providers.
+
+
+#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self) -> Sequence[Resource]
+```
+
+Return all available resources.
+
+Override to provide resources dynamically.
+
+
+#### `get_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource(self, uri: str) -> Resource | None
+```
+
+Get a specific resource by URI.
+
+Default implementation lists all resources and finds by URI.
+Override for more efficient single-resource lookup.
+
+**Returns:**
+- The Resource if found, or None to continue searching other providers.
+
+
+#### `list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self) -> Sequence[ResourceTemplate]
+```
+
+Return all available resource templates.
+
+Override to provide resource templates dynamically.
+
+
+#### `get_resource_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource_template(self, uri: str) -> ResourceTemplate | None
+```
+
+Get a resource template that matches the given URI.
+
+Default implementation lists all templates and finds one whose pattern
+matches the URI.
+Override for more efficient lookup.
+
+**Returns:**
+- The ResourceTemplate if a matching one is found, or None to continue searching.
+
+
+#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L192" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self) -> Sequence[Prompt]
+```
+
+Return all available prompts.
+
+Override to provide prompts dynamically.
+
+
+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(self, name: str) -> Prompt | None
+```
+
+Get a specific prompt by name.
+
+Default implementation lists all prompts and finds by name.
+Override for more efficient single-prompt lookup.
+
+**Returns:**
+- The Prompt if found, or None to continue searching other providers.
+
+
+#### `get_component` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L211" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_component(self, key: str) -> Tool | Resource | ResourceTemplate | Prompt | None
+```
+
+Get a component by its prefixed key.
+
+**Args:**
+- `key`: The prefixed key (e.g., "tool\:name", "resource\:uri", "template\:uri").
+
+**Returns:**
+- The component if found, or None to continue searching other providers.
+
+
+#### `get_tasks` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L241" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tasks(self) -> Sequence[FastMCPComponent]
+```
+
+Return components that should be registered as background tasks.
+
+Override to customize which components are task-eligible.
+Default calls list_* methods and filters for function-based components
+with task_config.mode != 'forbidden'.
+
+Used by the server during startup to register functions with Docket.
+
+
+#### `lifespan` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+lifespan(self) -> AsyncIterator[None]
+```
+
+User-overridable lifespan for custom setup and teardown.
+
+Override this method to perform provider-specific initialization
+like opening database connections, setting up external resources,
+or other state management needed for the provider's lifetime.
+
+The lifespan scope matches the server's lifespan - code before yield
+runs at startup, code after yield runs at shutdown.
+
+
+#### `enable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L312" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+enable(self) -> None
+```
+
+Enable components by removing from blocklist, or set allowlist with only=True.
+
+**Args:**
+- `keys`: Keys to enable (e.g., "tool\:my_tool").
+- `tags`: Tags to enable - components with these tags will be enabled.
+- `only`: If True, switches to allowlist mode - ONLY show these keys/tags.
+
+
+#### `disable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L328" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+disable(self) -> None
+```
+
+Disable components by adding to the blocklist.
+
+**Args:**
+- `keys`: Keys to disable (e.g., "tool\:my_tool").
+- `tags`: Tags to disable - components with these tags will be disabled.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-fastmcp_provider.mdx b/docs/python-sdk/fastmcp-server-providers-fastmcp_provider.mdx
new file mode 100644
index 000000000..a93457ff5
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-fastmcp_provider.mdx
@@ -0,0 +1,328 @@
+---
+title: fastmcp_provider
+sidebarTitle: fastmcp_provider
+---
+
+# `fastmcp.server.providers.fastmcp_provider`
+
+
+FastMCPProvider for wrapping FastMCP servers as providers.
+
+This module provides the `FastMCPProvider` class that wraps a FastMCP server
+and exposes its components through the Provider interface.
+
+It also provides FastMCPProvider* component classes that delegate execution to
+the wrapped server's middleware, ensuring middleware runs when components are
+executed.
+
+
+## Classes
+
+### `FastMCPProviderTool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Tool that delegates execution to a wrapped server's middleware.
+
+When `run()` is called, this tool invokes the wrapped server's
+`_call_tool_middleware()` method, ensuring the server's middleware
+chain is executed.
+
+
+**Methods:**
+
+#### `wrap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wrap(cls, server: Any, tool: Tool) -> FastMCPProviderTool
+```
+
+Wrap a Tool to delegate execution to the server's middleware.
+
+
+#### `run` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(self, arguments: dict[str, Any]) -> ToolResult | mcp.types.CreateTaskResult
+```
+
+Delegate to child server's middleware chain.
+
+This runs BEFORE any backgrounding decision - the actual underlying
+tool will check contextvars and submit to Docket if appropriate.
+
+
+### `FastMCPProviderResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Resource that delegates reading to a wrapped server's middleware.
+
+When `read()` is called, this resource invokes the wrapped server's
+`_read_resource_middleware()` method, ensuring the server's middleware
+chain is executed.
+
+
+**Methods:**
+
+#### `wrap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wrap(cls, server: Any, resource: Resource) -> FastMCPProviderResource
+```
+
+Wrap a Resource to delegate reading to the server's middleware.
+
+
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> ResourceContent | mcp.types.CreateTaskResult
+```
+
+Delegate to child server's middleware.
+
+When called from a Docket worker (background task), there's no FastMCP
+context set up, so we create one for the child server.
+
+Note: The _docket_fn_key contextvar is intentionally NOT updated here.
+The parent set it to the full namespaced key (e.g., data://c/gc/value)
+which is what the function is registered under in Docket. All provider
+layers pass this through unchanged so the eventual resource._read()
+uses the correct Docket lookup key.
+
+
+### `FastMCPProviderPrompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L185" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Prompt that delegates rendering to a wrapped server's middleware.
+
+When `render()` is called, this prompt invokes the wrapped server's
+`_get_prompt_content_middleware()` method, ensuring the server's middleware
+chain is executed.
+
+
+**Methods:**
+
+#### `wrap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wrap(cls, server: Any, prompt: Prompt) -> FastMCPProviderPrompt
+```
+
+Wrap a Prompt to delegate rendering to the server's middleware.
+
+
+#### `render` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L229" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+render(self, arguments: dict[str, Any] | None = None) -> PromptResult | mcp.types.CreateTaskResult
+```
+
+Delegate to child server's middleware.
+
+When called from a Docket worker (background task), there's no FastMCP
+context set up, so we create one for the child server.
+
+Note: The _docket_fn_key contextvar is intentionally NOT updated here.
+The parent set it to the full namespaced name (e.g., c_gc_greet) which
+is what the function is registered under in Docket. All provider layers
+pass this through unchanged so the eventual prompt._render() uses the
+correct Docket lookup key.
+
+
+### `FastMCPProviderResourceTemplate` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L266" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Resource template that creates FastMCPProviderResources.
+
+When `create_resource()` is called, this template creates a
+FastMCPProviderResource that will invoke the wrapped server's middleware
+when read.
+
+
+**Methods:**
+
+#### `wrap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L288" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wrap(cls, server: Any, template: ResourceTemplate) -> FastMCPProviderResourceTemplate
+```
+
+Wrap a ResourceTemplate to create FastMCPProviderResources.
+
+
+#### `create_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_resource(self, uri: str, params: dict[str, Any]) -> Resource
+```
+
+Create a FastMCPProviderResource for the given URI.
+
+The `uri` is the external/transformed URI (e.g., with namespace prefix).
+We use `_original_uri_template` with `params` to construct the internal
+URI that the nested server understands.
+
+
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self, arguments: dict[str, Any]) -> str | bytes
+```
+
+Read the resource content for background task execution.
+
+Creates a resource from this template and reads its content.
+This method is called by Docket during background task execution.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L401" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+No-op: the child's actual template is registered via get_tasks().
+
+
+#### `add_to_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L404" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, params: dict[str, Any], **kwargs: Any) -> Execution
+```
+
+Schedule this template for background execution via docket.
+
+The child's FunctionResourceTemplate.fn is registered (via get_tasks),
+and it expects splatted **kwargs, so we splat params here.
+
+
+### `FastMCPProvider` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L429" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Provider that wraps a FastMCP server.
+
+This provider enables mounting one FastMCP server onto another, exposing
+the mounted server's tools, resources, and prompts through the parent
+server.
+
+Components returned by this provider are wrapped in FastMCPProvider*
+classes that delegate execution to the wrapped server's middleware chain.
+This ensures middleware runs when components are executed.
+
+
+**Methods:**
+
+#### `list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L477" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self) -> Sequence[Tool]
+```
+
+List all tools from the mounted server as FastMCPProviderTools.
+
+Calls the nested server's middleware to list tools, then wraps
+each tool as a FastMCPProviderTool that delegates execution to the
+nested server's middleware.
+
+
+#### `get_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L487" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str) -> Tool | None
+```
+
+Get a tool by name as a FastMCPProviderTool.
+
+
+#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L496" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self) -> Sequence[Resource]
+```
+
+List all resources from the mounted server as FastMCPProviderResources.
+
+Calls the nested server's middleware to list resources, then wraps
+each resource as a FastMCPProviderResource that delegates reading to the
+nested server's middleware.
+
+
+#### `get_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L506" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource(self, uri: str) -> Resource | None
+```
+
+Get a concrete resource by URI as a FastMCPProviderResource.
+
+
+#### `list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L515" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self) -> Sequence[ResourceTemplate]
+```
+
+List all resource templates from the mounted server.
+
+Returns FastMCPProviderResourceTemplate instances that create
+FastMCPProviderResources when materialized.
+
+
+#### `get_resource_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L526" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource_template(self, uri: str) -> ResourceTemplate | None
+```
+
+Get a resource template that matches the given URI.
+
+
+#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L538" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self) -> Sequence[Prompt]
+```
+
+List all prompts from the mounted server as FastMCPProviderPrompts.
+
+Returns FastMCPProviderPrompt instances that delegate rendering to the
+wrapped server's middleware.
+
+
+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L547" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(self, name: str) -> Prompt | None
+```
+
+Get a prompt by name as a FastMCPProviderPrompt.
+
+
+#### `get_tasks` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L556" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tasks(self) -> Sequence[FastMCPComponent]
+```
+
+Return task-eligible components from the mounted server.
+
+Returns the child's ACTUAL components (not wrapped) so their actual
+functions get registered with Docket. TransformingProvider.get_tasks()
+handles namespace transformation of keys.
+
+Iterates through all providers in the wrapped server (including its
+LocalProvider) to collect task-eligible components.
+
+
+#### `lifespan` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L576" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+lifespan(self) -> AsyncIterator[None]
+```
+
+Start the mounted server's user lifespan.
+
+This starts only the wrapped server's user-defined lifespan, NOT its
+full _lifespan_manager() (which includes Docket). The parent server's
+Docket handles all background tasks.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider.mdx
new file mode 100644
index 000000000..40c4141e1
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-local_provider.mdx
@@ -0,0 +1,372 @@
+---
+title: local_provider
+sidebarTitle: local_provider
+---
+
+# `fastmcp.server.providers.local_provider`
+
+
+LocalProvider for locally-defined MCP components.
+
+This module provides the `LocalProvider` class that manages tools, resources,
+templates, and prompts registered via decorators or direct methods.
+
+LocalProvider can be used standalone and attached to multiple servers:
+
+```python
+from fastmcp.server.providers import LocalProvider
+
+# Create a reusable provider with tools
+provider = LocalProvider()
+
+def greet(name: str) -> str:
+ return f"Hello, {name}!"
+
+# Attach to any server
+from fastmcp import FastMCP
+server1 = FastMCP("Server1", providers=[provider])
+server2 = FastMCP("Server2", providers=[provider])
+```
+
+
+## Classes
+
+### `LocalProvider` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Provider for locally-defined components.
+
+Supports decorator-based registration (`@provider.tool`, `@provider.resource`,
+`@provider.prompt`) and direct object registration methods.
+
+When used standalone, LocalProvider uses default settings. When attached
+to a FastMCP server via the server's decorators, server-level settings
+like `_tool_serializer` and `_support_tasks_by_default` are injected.
+
+
+**Methods:**
+
+#### `add_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_tool(self, tool: Tool) -> Tool
+```
+
+Add a tool to this provider's storage.
+
+
+#### `remove_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L186" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+remove_tool(self, name: str) -> None
+```
+
+Remove a tool from this provider's storage.
+
+
+#### `add_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_resource(self, resource: Resource) -> Resource
+```
+
+Add a resource to this provider's storage.
+
+
+#### `remove_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L194" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+remove_resource(self, uri: str) -> None
+```
+
+Remove a resource from this provider's storage.
+
+
+#### `add_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L198" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_template(self, template: ResourceTemplate) -> ResourceTemplate
+```
+
+Add a resource template to this provider's storage.
+
+
+#### `remove_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+remove_template(self, uri_template: str) -> None
+```
+
+Remove a resource template from this provider's storage.
+
+
+#### `add_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L206" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_prompt(self, prompt: Prompt) -> Prompt
+```
+
+Add a prompt to this provider's storage.
+
+
+#### `remove_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L210" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+remove_prompt(self, name: str) -> None
+```
+
+Remove a prompt from this provider's storage.
+
+
+#### `add_tool_transformation` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_tool_transformation(self, tool_name: str, transformation: ToolTransformConfig) -> None
+```
+
+Add a tool transformation.
+
+**Args:**
+- `tool_name`: The name of the tool to transform.
+- `transformation`: The transformation configuration.
+
+
+#### `get_tool_transformation` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L229" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool_transformation(self, tool_name: str) -> ToolTransformConfig | None
+```
+
+Get a tool transformation.
+
+**Args:**
+- `tool_name`: The name of the tool.
+
+**Returns:**
+- The transformation config, or None if not found.
+
+
+#### `remove_tool_transformation` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+remove_tool_transformation(self, tool_name: str) -> None
+```
+
+Remove a tool transformation.
+
+**Args:**
+- `tool_name`: The name of the tool.
+
+
+#### `list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self) -> Sequence[Tool]
+```
+
+Return all visible tools with transformations applied.
+
+
+#### `get_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L262" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str) -> Tool | None
+```
+
+Get a tool by name, with transformations applied.
+
+
+#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L267" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self) -> Sequence[Resource]
+```
+
+Return all visible resources.
+
+
+#### `get_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L275" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource(self, uri: str) -> Resource | None
+```
+
+Get a resource by URI if visible.
+
+
+#### `list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L282" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self) -> Sequence[ResourceTemplate]
+```
+
+Return all visible resource templates.
+
+
+#### `get_resource_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource_template(self, uri: str) -> ResourceTemplate | None
+```
+
+Get a resource template that matches the given URI if visible.
+
+
+#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L301" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self) -> Sequence[Prompt]
+```
+
+Return all visible prompts.
+
+
+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(self, name: str) -> Prompt | None
+```
+
+Get a prompt by name if visible.
+
+
+#### `get_component` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L316" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_component(self, key: str) -> Tool | Resource | ResourceTemplate | Prompt | None
+```
+
+Get a component by its prefixed key.
+
+Efficient O(1) lookup in the unified components dict.
+
+
+#### `get_tasks` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L332" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tasks(self) -> Sequence[FastMCPComponent]
+```
+
+Return components eligible for background task execution.
+
+Returns components that have task_config.mode != 'forbidden'.
+This includes both FunctionTool/Resource/Prompt instances created via
+decorators and custom Tool/Resource/Prompt subclasses.
+
+
+#### `tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L346" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self, name_or_fn: AnyFunction) -> FunctionTool
+```
+
+#### `tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L365" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionTool]
+```
+
+#### `tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L383" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionTool] | FunctionTool | partial[Callable[[AnyFunction], FunctionTool] | FunctionTool]
+```
+
+Decorator to register a tool.
+
+This decorator supports multiple calling patterns:
+- @provider.tool (without parentheses)
+- @provider.tool() (with empty parentheses)
+- @provider.tool("custom_name") (with name as first argument)
+- @provider.tool(name="custom_name") (with name as keyword argument)
+- provider.tool(function, name="custom_name") (direct function call)
+
+**Args:**
+- `name_or_fn`: Either a function (when used as @tool), a string name, or None
+- `name`: Optional name for the tool (keyword-only, alternative to name_or_fn)
+- `title`: Optional title for the tool
+- `description`: Optional description of what the tool does
+- `icons`: Optional icons for the tool
+- `tags`: Optional set of tags for categorizing the tool
+- `output_schema`: Optional JSON schema for the tool's output
+- `annotations`: Optional annotations about the tool's behavior
+- `exclude_args`: Optional list of argument names to exclude from the tool schema
+- `meta`: Optional meta information about the tool
+- `enabled`: Whether the tool is enabled (default True). If False, adds to blocklist.
+- `task`: Optional task configuration for background execution
+- `serializer`: Optional serializer for the tool result
+
+**Returns:**
+- The registered FunctionTool or a decorator function.
+
+
+#### `resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L523" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+resource(self, uri: str) -> Callable[[AnyFunction], Resource | ResourceTemplate]
+```
+
+Decorator to register a function as a resource.
+
+If the URI contains parameters (e.g. "resource://{param}") or the function
+has parameters, it will be registered as a template resource.
+
+**Args:**
+- `uri`: URI for the resource (e.g. "resource\://my-resource" or "resource\://{param}")
+- `name`: Optional name for the resource
+- `title`: Optional title for the resource
+- `description`: Optional description of the resource
+- `icons`: Optional icons for the resource
+- `mime_type`: Optional MIME type for the resource
+- `tags`: Optional set of tags for categorizing the resource
+- `enabled`: Whether the resource is enabled (default True). If False, adds to blocklist.
+- `annotations`: Optional annotations about the resource's behavior
+- `meta`: Optional meta information about the resource
+- `task`: Optional task configuration for background execution
+
+**Returns:**
+- A decorator function.
+
+
+#### `prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L653" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prompt(self, name_or_fn: AnyFunction) -> FunctionPrompt
+```
+
+#### `prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L668" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prompt(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionPrompt]
+```
+
+#### `prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/local_provider.py#L682" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prompt(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt | partial[Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt]
+```
+
+Decorator to register a prompt.
+
+This decorator supports multiple calling patterns:
+- @provider.prompt (without parentheses)
+- @provider.prompt() (with empty parentheses)
+- @provider.prompt("custom_name") (with name as first argument)
+- @provider.prompt(name="custom_name") (with name as keyword argument)
+- provider.prompt(function, name="custom_name") (direct function call)
+
+**Args:**
+- `name_or_fn`: Either a function (when used as @prompt), a string name, or None
+- `name`: Optional name for the prompt (keyword-only, alternative to name_or_fn)
+- `title`: Optional title for the prompt
+- `description`: Optional description of what the prompt does
+- `icons`: Optional icons for the prompt
+- `tags`: Optional set of tags for categorizing the prompt
+- `enabled`: Whether the prompt is enabled (default True). If False, adds to blocklist.
+- `meta`: Optional meta information about the prompt
+- `task`: Optional task configuration for background execution
+
+**Returns:**
+- The registered FunctionPrompt or a decorator function.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-openapi-__init__.mdx b/docs/python-sdk/fastmcp-server-providers-openapi-__init__.mdx
new file mode 100644
index 000000000..bd79a038b
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-openapi-__init__.mdx
@@ -0,0 +1,23 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.providers.openapi`
+
+
+OpenAPI provider for FastMCP.
+
+This module provides OpenAPI integration for FastMCP through the Provider pattern.
+
+Example:
+ ```python
+ from fastmcp import FastMCP
+ from fastmcp.server.providers.openapi import OpenAPIProvider
+ import httpx
+
+ client = httpx.AsyncClient(base_url="https://api.example.com")
+ provider = OpenAPIProvider(openapi_spec=spec, client=client)
+ mcp = FastMCP("API Server", providers=[provider])
+ ```
+
diff --git a/docs/python-sdk/fastmcp-server-providers-openapi-components.mdx b/docs/python-sdk/fastmcp-server-providers-openapi-components.mdx
new file mode 100644
index 000000000..fa5728a3b
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-openapi-components.mdx
@@ -0,0 +1,62 @@
+---
+title: components
+sidebarTitle: components
+---
+
+# `fastmcp.server.providers.openapi.components`
+
+
+OpenAPI component classes: Tool, Resource, and ResourceTemplate.
+
+## Classes
+
+### `OpenAPITool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/components.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Tool implementation for OpenAPI endpoints.
+
+
+**Methods:**
+
+#### `run` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/components.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(self, arguments: dict[str, Any]) -> ToolResult
+```
+
+Execute the HTTP request using RequestDirector.
+
+
+### `OpenAPIResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/components.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Resource implementation for OpenAPI endpoints.
+
+
+**Methods:**
+
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/components.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> ResourceContent
+```
+
+Fetch the resource data by making an HTTP request.
+
+
+### `OpenAPIResourceTemplate` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/components.py#L258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Resource template implementation for OpenAPI endpoints.
+
+
+**Methods:**
+
+#### `create_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/components.py#L290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_resource(self, uri: str, params: dict[str, Any], context: Context | None = None) -> Resource
+```
+
+Create a resource with the given parameters.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-openapi-provider.mdx b/docs/python-sdk/fastmcp-server-providers-openapi-provider.mdx
new file mode 100644
index 000000000..2df5a6449
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-openapi-provider.mdx
@@ -0,0 +1,94 @@
+---
+title: provider
+sidebarTitle: provider
+---
+
+# `fastmcp.server.providers.openapi.provider`
+
+
+OpenAPIProvider for creating MCP components from OpenAPI specifications.
+
+## Classes
+
+### `OpenAPIProvider` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/provider.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Provider that creates MCP components from an OpenAPI specification.
+
+Components are created eagerly during initialization by parsing the OpenAPI
+spec. Each component makes HTTP calls to the described API endpoints.
+
+
+**Methods:**
+
+#### `list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/provider.py#L351" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self) -> Sequence[Tool]
+```
+
+Return all tools created from the OpenAPI spec.
+
+
+#### `get_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/provider.py#L355" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str) -> Tool | None
+```
+
+Get a tool by name.
+
+
+#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/provider.py#L359" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self) -> Sequence[Resource]
+```
+
+Return all resources created from the OpenAPI spec.
+
+
+#### `get_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/provider.py#L363" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource(self, uri: str) -> Resource | None
+```
+
+Get a resource by URI.
+
+
+#### `list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/provider.py#L367" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self) -> Sequence[ResourceTemplate]
+```
+
+Return all resource templates created from the OpenAPI spec.
+
+
+#### `get_resource_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/provider.py#L371" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource_template(self, uri: str) -> ResourceTemplate | None
+```
+
+Get a resource template that matches the given URI.
+
+
+#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/provider.py#L378" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self) -> Sequence[Prompt]
+```
+
+Return empty list - OpenAPI doesn't create prompts.
+
+
+#### `get_tasks` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/provider.py#L382" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tasks(self) -> Sequence[FastMCPComponent]
+```
+
+Return empty list - OpenAPI components don't support tasks.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-openapi-routing.mdx b/docs/python-sdk/fastmcp-server-providers-openapi-routing.mdx
new file mode 100644
index 000000000..6c0f8b3c7
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-openapi-routing.mdx
@@ -0,0 +1,23 @@
+---
+title: routing
+sidebarTitle: routing
+---
+
+# `fastmcp.server.providers.openapi.routing`
+
+
+Route mapping logic for OpenAPI operations.
+
+## Classes
+
+### `MCPType` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/routing.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Type of FastMCP component to create from a route.
+
+
+### `RouteMap` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/openapi/routing.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Mapping configuration for HTTP routes to FastMCP component types.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-proxy.mdx b/docs/python-sdk/fastmcp-server-providers-proxy.mdx
new file mode 100644
index 000000000..866109ca9
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-proxy.mdx
@@ -0,0 +1,322 @@
+---
+title: proxy
+sidebarTitle: proxy
+---
+
+# `fastmcp.server.providers.proxy`
+
+
+ProxyProvider for proxying to remote MCP servers.
+
+This module provides the `ProxyProvider` class that proxies components from
+a remote MCP server via a client factory. It also provides proxy component
+classes that forward execution to remote servers.
+
+
+## Functions
+
+### `default_proxy_roots_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L608" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_proxy_roots_handler(context: RequestContext[ClientSession, LifespanContextT]) -> RootsList
+```
+
+
+Forward list roots request from remote server to proxy's connected clients.
+
+
+### `default_proxy_sampling_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L616" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_proxy_sampling_handler(messages: list[mcp.types.SamplingMessage], params: mcp.types.CreateMessageRequestParams, context: RequestContext[ClientSession, LifespanContextT]) -> mcp.types.CreateMessageResult
+```
+
+
+Forward sampling request from remote server to proxy's connected clients.
+
+
+### `default_proxy_elicitation_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L639" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_proxy_elicitation_handler(message: str, response_type: type, params: mcp.types.ElicitRequestParams, context: RequestContext[ClientSession, LifespanContextT]) -> ElicitResult
+```
+
+
+Forward elicitation request from remote server to proxy's connected clients.
+
+
+### `default_proxy_log_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L661" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_proxy_log_handler(message: LogMessage) -> None
+```
+
+
+Forward log notification from remote server to proxy's connected clients.
+
+
+### `default_proxy_progress_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L669" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_proxy_progress_handler(progress: float, total: float | None, message: str | None) -> None
+```
+
+
+Forward progress notification from remote server to proxy's connected clients.
+
+
+## Classes
+
+### `ProxyTool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Tool that represents and executes a tool on a remote server.
+
+
+**Methods:**
+
+#### `model_copy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+model_copy(self, **kwargs: Any) -> ProxyTool
+```
+
+Override to preserve _backend_name when name changes.
+
+
+#### `from_mcp_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_mcp_tool(cls, client_factory: ClientFactoryT, mcp_tool: mcp.types.Tool) -> ProxyTool
+```
+
+Factory method to create a ProxyTool from a raw MCP tool schema.
+
+
+#### `run` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(self, arguments: dict[str, Any], context: Context | None = None) -> ToolResult
+```
+
+Executes the tool by making a call through the client.
+
+
+### `ProxyResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Resource that represents and reads a resource from a remote server.
+
+
+**Methods:**
+
+#### `model_copy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+model_copy(self, **kwargs: Any) -> ProxyResource
+```
+
+Override to preserve _backend_uri when uri changes.
+
+
+#### `from_mcp_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_mcp_resource(cls, client_factory: ClientFactoryT, mcp_resource: mcp.types.Resource) -> ProxyResource
+```
+
+Factory method to create a ProxyResource from a raw MCP resource schema.
+
+
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L208" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> ResourceContent
+```
+
+Read the resource content from the remote server.
+
+
+### `ProxyTemplate` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A ResourceTemplate that represents and creates resources from a remote server template.
+
+
+**Methods:**
+
+#### `model_copy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+model_copy(self, **kwargs: Any) -> ProxyTemplate
+```
+
+Override to preserve _backend_uri_template when uri_template changes.
+
+
+#### `from_mcp_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L264" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_mcp_template(cls, client_factory: ClientFactoryT, mcp_template: mcp.types.ResourceTemplate) -> ProxyTemplate
+```
+
+Factory method to create a ProxyTemplate from a raw MCP template schema.
+
+
+#### `create_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_resource(self, uri: str, params: dict[str, Any], context: Context | None = None) -> ProxyResource
+```
+
+Create a resource from the template by calling the remote server.
+
+
+### `ProxyPrompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L334" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Prompt that represents and renders a prompt from a remote server.
+
+
+**Methods:**
+
+#### `model_copy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L351" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+model_copy(self, **kwargs: Any) -> ProxyPrompt
+```
+
+Override to preserve _backend_name when name changes.
+
+
+#### `from_mcp_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L361" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_mcp_prompt(cls, client_factory: ClientFactoryT, mcp_prompt: mcp.types.Prompt) -> ProxyPrompt
+```
+
+Factory method to create a ProxyPrompt from a raw MCP prompt schema.
+
+
+#### `render` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L385" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+render(self, arguments: dict[str, Any]) -> PromptResult
+```
+
+Render the prompt by making a call through the client.
+
+
+### `ProxyProvider` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L404" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Provider that proxies to a remote MCP server via a client factory.
+
+This provider fetches components from a remote server and returns Proxy*
+component instances that forward execution to the remote server.
+
+All components returned by this provider have task_config.mode="forbidden"
+because tasks cannot be executed through a proxy.
+
+
+**Methods:**
+
+#### `list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L458" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self) -> Sequence[Tool]
+```
+
+List all tools from the remote server.
+
+
+#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L483" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self) -> Sequence[Resource]
+```
+
+List all resources from the remote server.
+
+
+#### `list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L502" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self) -> Sequence[ResourceTemplate]
+```
+
+List all resource templates from the remote server.
+
+
+#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L521" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self) -> Sequence[Prompt]
+```
+
+List all prompts from the remote server.
+
+
+#### `get_tasks` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L540" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tasks(self) -> Sequence[FastMCPComponent]
+```
+
+Return empty list since proxy components don't support tasks.
+
+Override the base implementation to avoid calling list_tools() during
+server lifespan initialization, which would open the client before any
+context is set. All Proxy* components have task_config.mode="forbidden".
+
+
+### `FastMCPProxy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L558" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A FastMCP server that acts as a proxy to a remote MCP-compliant server.
+
+This is a convenience wrapper that creates a FastMCP server with a
+ProxyProvider. For more control, use FastMCP with add_provider(ProxyProvider(...)).
+
+
+### `ProxyClient` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L679" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A proxy client that forwards advanced interactions between a remote MCP server and the proxy's connected clients.
+
+Supports forwarding roots, sampling, elicitation, logging, and progress.
+
+
+### `StatefulProxyClient` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L716" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A proxy client that provides a stateful client factory for the proxy server.
+
+The stateful proxy client bound its copy to the server session.
+And it will be disconnected when the session is exited.
+
+This is useful to proxy a stateful mcp server such as the Playwright MCP server.
+Note that it is essential to ensure that the proxy server itself is also stateful.
+
+
+**Methods:**
+
+#### `clear` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L736" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+clear(self)
+```
+
+Clear all cached clients and force disconnect them.
+
+
+#### `new_stateful` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L742" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+new_stateful(self) -> Client[ClientTransportT]
+```
+
+Create a new stateful proxy client instance with the same configuration.
+
+Use this method as the client factory for stateful proxy server.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-transforming.mdx b/docs/python-sdk/fastmcp-server-providers-transforming.mdx
new file mode 100644
index 000000000..94952eac2
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-transforming.mdx
@@ -0,0 +1,117 @@
+---
+title: transforming
+sidebarTitle: transforming
+---
+
+# `fastmcp.server.providers.transforming`
+
+
+TransformingProvider for applying component transformations.
+
+This module provides the `TransformingProvider` class that wraps any Provider
+and applies transformations like namespace prefixes and tool renames.
+
+
+## Classes
+
+### `TransformingProvider` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/transforming.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Wraps any provider and applies component transformations.
+
+Users typically use `provider.with_transforms()` rather than instantiating
+this class directly. Multiple `.with_transforms()` calls stack - each
+creates a new wrapper that composes with the previous.
+
+
+**Methods:**
+
+#### `list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/transforming.py#L169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self) -> Sequence[Tool]
+```
+
+List tools with transformations applied.
+
+
+#### `get_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/transforming.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str) -> Tool | None
+```
+
+Get tool by transformed name.
+
+
+#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/transforming.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self) -> Sequence[Resource]
+```
+
+List resources with URI transformations applied.
+
+
+#### `get_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/transforming.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource(self, uri: str) -> Resource | None
+```
+
+Get resource by transformed URI.
+
+
+#### `list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/transforming.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self) -> Sequence[ResourceTemplate]
+```
+
+List resource templates with URI transformations applied.
+
+
+#### `get_resource_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/transforming.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource_template(self, uri: str) -> ResourceTemplate | None
+```
+
+Get resource template by transformed URI.
+
+
+#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/transforming.py#L241" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self) -> Sequence[Prompt]
+```
+
+List prompts with transformations applied.
+
+
+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/transforming.py#L249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(self, name: str) -> Prompt | None
+```
+
+Get prompt by transformed name.
+
+
+#### `get_tasks` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/transforming.py#L263" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tasks(self) -> Sequence[FastMCPComponent]
+```
+
+Get tasks with transformations applied to all components.
+
+
+#### `lifespan` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/providers/transforming.py#L304" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+lifespan(self) -> AsyncIterator[None]
+```
+
+Delegate lifespan to wrapped provider.
+
diff --git a/docs/python-sdk/fastmcp-server-proxy.mdx b/docs/python-sdk/fastmcp-server-proxy.mdx
index 9abe6e123..a9200635c 100644
--- a/docs/python-sdk/fastmcp-server-proxy.mdx
+++ b/docs/python-sdk/fastmcp-server-proxy.mdx
@@ -5,335 +5,10 @@ sidebarTitle: proxy
# `fastmcp.server.proxy`
-## Functions
-### `default_proxy_roots_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+Backwards compatibility - import from fastmcp.server.providers.proxy instead.
-```python
-default_proxy_roots_handler(context: RequestContext[ClientSession, LifespanContextT]) -> RootsList
-```
-
-
-A handler that forwards the list roots request from the remote server to the proxy's connected clients and relays the response back to the remote server.
-
-
-## Classes
-
-### `ProxyManagerMixin` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-A mixin for proxy managers to provide a unified client retrieval method.
-
-
-### `ProxyToolManager` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-A ToolManager that sources its tools from a remote client in addition to local and mounted tools.
-
-
-**Methods:**
-
-#### `get_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-get_tools(self) -> dict[str, Tool]
-```
-
-Gets the unfiltered tool inventory including local, mounted, and proxy tools.
-
-
-#### `list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-list_tools(self) -> list[Tool]
-```
-
-Gets the filtered list of tools including local, mounted, and proxy tools.
-
-
-#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-call_tool(self, key: str, arguments: dict[str, Any]) -> ToolResult
-```
-
-Calls a tool, trying local/mounted first, then proxy if not found.
-
-
-### `ProxyResourceManager` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-A ResourceManager that sources its resources from a remote client in addition to local and mounted resources.
-
-
-**Methods:**
-
-#### `get_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L131" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-get_resources(self) -> dict[str, Resource]
-```
-
-Gets the unfiltered resource inventory including local, mounted, and proxy resources.
-
-
-#### `get_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-get_resource_templates(self) -> dict[str, ResourceTemplate]
-```
-
-Gets the unfiltered template inventory including local, mounted, and proxy templates.
-
-
-#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-list_resources(self) -> list[Resource]
-```
-
-Gets the filtered list of resources including local, mounted, and proxy resources.
-
-
-#### `list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-list_resource_templates(self) -> list[ResourceTemplate]
-```
-
-Gets the filtered list of templates including local, mounted, and proxy templates.
-
-
-#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-read_resource(self, uri: AnyUrl | str) -> str | bytes
-```
-
-Reads a resource, trying local/mounted first, then proxy if not found.
-
-
-### `ProxyPromptManager` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-A PromptManager that sources its prompts from a remote client in addition to local and mounted prompts.
-
-
-**Methods:**
-
-#### `get_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L214" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-get_prompts(self) -> dict[str, Prompt]
-```
-
-Gets the unfiltered prompt inventory including local, mounted, and proxy prompts.
-
-
-#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-list_prompts(self) -> list[Prompt]
-```
-
-Gets the filtered list of prompts including local, mounted, and proxy prompts.
-
-
-#### `render_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L242" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-render_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> GetPromptResult
-```
-
-Renders a prompt, trying local/mounted first, then proxy if not found.
-
-
-### `ProxyTool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-A Tool that represents and executes a tool on a remote server.
-
-
-**Methods:**
-
-#### `from_mcp_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L271" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-from_mcp_tool(cls, client: Client, mcp_tool: mcp.types.Tool) -> ProxyTool
-```
-
-Factory method to create a ProxyTool from a raw MCP tool schema.
-
-
-#### `run` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-run(self, arguments: dict[str, Any], context: Context | None = None) -> ToolResult
-```
-
-Executes the tool by making a call through the client.
-
-
-### `ProxyResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L328" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-A Resource that represents and reads a resource from a remote server.
-
-
-**Methods:**
-
-#### `from_mcp_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L349" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-from_mcp_resource(cls, client: Client, mcp_resource: mcp.types.Resource) -> ProxyResource
-```
-
-Factory method to create a ProxyResource from a raw MCP resource schema.
-
-
-#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L370" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-read(self) -> str | bytes
-```
-
-Read the resource content from the remote server.
-
-
-### `ProxyTemplate` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L385" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-A ResourceTemplate that represents and creates resources from a remote server template.
-
-
-**Methods:**
-
-#### `from_mcp_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L397" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-from_mcp_template(cls, client: Client, mcp_template: mcp.types.ResourceTemplate) -> ProxyTemplate
-```
-
-Factory method to create a ProxyTemplate from a raw MCP template schema.
-
-
-#### `create_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L416" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-create_resource(self, uri: str, params: dict[str, Any], context: Context | None = None) -> ProxyResource
-```
-
-Create a resource from the template by calling the remote server.
-
-
-### `ProxyPrompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L453" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-A Prompt that represents and renders a prompt from a remote server.
-
-
-**Methods:**
-
-#### `from_mcp_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L466" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-from_mcp_prompt(cls, client: Client, mcp_prompt: mcp.types.Prompt) -> ProxyPrompt
-```
-
-Factory method to create a ProxyPrompt from a raw MCP prompt schema.
-
-
-#### `render` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L491" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-render(self, arguments: dict[str, Any]) -> list[PromptMessage]
-```
-
-Render the prompt by making a call through the client.
-
-
-### `FastMCPProxy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L498" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-A FastMCP server that acts as a proxy to a remote MCP-compliant server.
-It uses specialized managers that fulfill requests via a client factory.
-
-
-### `ProxyClient` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L549" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-A proxy client that forwards advanced interactions between a remote MCP server and the proxy's connected clients.
-Supports forwarding roots, sampling, elicitation, logging, and progress.
-
-
-**Methods:**
-
-#### `default_sampling_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L582" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-default_sampling_handler(cls, messages: list[mcp.types.SamplingMessage], params: mcp.types.CreateMessageRequestParams, context: RequestContext[ClientSession, LifespanContextT]) -> mcp.types.CreateMessageResult
-```
-
-A handler that forwards the sampling request from the remote server to the proxy's connected clients and relays the response back to the remote server.
-
-
-#### `default_elicitation_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L609" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-default_elicitation_handler(cls, message: str, response_type: type, params: mcp.types.ElicitRequestParams, context: RequestContext[ClientSession, LifespanContextT]) -> ElicitResult
-```
-
-A handler that forwards the elicitation request from the remote server to the proxy's connected clients and relays the response back to the remote server.
-
-
-#### `default_log_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L634" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-default_log_handler(cls, message: LogMessage) -> None
-```
-
-A handler that forwards the log notification from the remote server to the proxy's connected clients.
-
-
-#### `default_progress_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L644" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-default_progress_handler(cls, progress: float, total: float | None, message: str | None) -> None
-```
-
-A handler that forwards the progress notification from the remote server to the proxy's connected clients.
-
-
-### `StatefulProxyClient` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L657" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-A proxy client that provides a stateful client factory for the proxy server.
-
-The stateful proxy client bound its copy to the server session.
-And it will be disconnected when the session is exited.
-
-This is useful to proxy a stateful mcp server such as the Playwright MCP server.
-Note that it is essential to ensure that the proxy server itself is also stateful.
-
-
-**Methods:**
-
-#### `clear` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L678" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-clear(self)
-```
-
-Clear all cached clients and force disconnect them.
-
-
-#### `new_stateful` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/proxy.py#L686" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-new_stateful(self) -> Client[ClientTransportT]
-```
-
-Create a new stateful proxy client instance with the same configuration.
-
-Use this method as the client factory for stateful proxy server.
+This module re-exports all proxy-related classes from their new location
+at fastmcp.server.providers.proxy. Direct imports from this module are
+deprecated and will be removed in a future version.
diff --git a/docs/python-sdk/fastmcp-server-sampling-__init__.mdx b/docs/python-sdk/fastmcp-server-sampling-__init__.mdx
new file mode 100644
index 000000000..0b0533971
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-sampling-__init__.mdx
@@ -0,0 +1,9 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.sampling`
+
+
+Sampling module for FastMCP servers.
diff --git a/docs/python-sdk/fastmcp-server-sampling-run.mdx b/docs/python-sdk/fastmcp-server-sampling-run.mdx
new file mode 100644
index 000000000..16ea08a8f
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-sampling-run.mdx
@@ -0,0 +1,116 @@
+---
+title: run
+sidebarTitle: run
+---
+
+# `fastmcp.server.sampling.run`
+
+
+Sampling types and helper functions for FastMCP servers.
+
+## Functions
+
+### `determine_handler_mode` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+determine_handler_mode(context: Context, needs_tools: bool) -> bool
+```
+
+
+Determine whether to use fallback handler or client for sampling.
+
+**Args:**
+- `context`: The MCP context.
+- `needs_tools`: Whether the sampling request requires tool support.
+
+**Returns:**
+- True if fallback handler should be used, False to use client.
+
+**Raises:**
+- `ValueError`: If client lacks required capability and no fallback configured.
+
+
+### `call_sampling_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+call_sampling_handler(context: Context, messages: list[SamplingMessage]) -> CreateMessageResult | CreateMessageResultWithTools
+```
+
+
+Make LLM call using the fallback handler.
+
+Note: This function expects the caller (sample_step) to have validated that
+sampling_handler is set via determine_handler_mode(). The checks below are
+safeguards against internal misuse.
+
+
+### `execute_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+execute_tools(tool_calls: list[ToolUseContent], tool_map: dict[str, SamplingTool], mask_error_details: bool = False) -> list[ToolResultContent]
+```
+
+
+Execute tool calls and return results.
+
+**Args:**
+- `tool_calls`: List of tool use requests from the LLM.
+- `tool_map`: Mapping from tool name to SamplingTool.
+- `mask_error_details`: If True, mask detailed error messages from tool execution.
+When masked, only generic error messages are returned to the LLM.
+Tools can explicitly raise ToolError to bypass masking when they want
+to provide specific error messages to the LLM.
+
+**Returns:**
+- List of tool result content blocks.
+
+
+## Classes
+
+### `SamplingResult` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Result of a sampling operation.
+
+**Attributes:**
+- `text`: The text representation of the result (raw text or JSON for structured).
+- `result`: The typed result (str for text, parsed object for structured output).
+- `history`: All messages exchanged during sampling.
+
+
+### `SampleStep` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Result of a single sampling call.
+
+Represents what the LLM returned in this step plus the message history.
+
+
+**Methods:**
+
+#### `is_tool_use` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+is_tool_use(self) -> bool
+```
+
+True if the LLM is requesting tool execution.
+
+
+#### `text` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+text(self) -> str | None
+```
+
+Extract text from the response, if available.
+
+
+#### `tool_calls` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool_calls(self) -> list[ToolUseContent]
+```
+
+Get the list of tool calls from the response.
+
diff --git a/docs/python-sdk/fastmcp-server-sampling-sampling_tool.mdx b/docs/python-sdk/fastmcp-server-sampling-sampling_tool.mdx
new file mode 100644
index 000000000..cdcead1a4
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-sampling-sampling_tool.mdx
@@ -0,0 +1,76 @@
+---
+title: sampling_tool
+sidebarTitle: sampling_tool
+---
+
+# `fastmcp.server.sampling.sampling_tool`
+
+
+SamplingTool for use during LLM sampling requests.
+
+## Classes
+
+### `SamplingTool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/sampling_tool.py#L15" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A tool that can be used during LLM sampling.
+
+SamplingTools bundle a tool's schema (name, description, parameters) with
+an executor function, enabling servers to execute agentic workflows where
+the LLM can request tool calls during sampling.
+
+In most cases, pass functions directly to ctx.sample():
+
+ def search(query: str) -> str:
+ '''Search the web.'''
+ return web_search(query)
+
+ result = await context.sample(
+ messages="Find info about Python",
+ tools=[search], # Plain functions work directly
+ )
+
+Create a SamplingTool explicitly when you need custom name/description:
+
+ tool = SamplingTool.from_function(search, name="web_search")
+
+
+**Methods:**
+
+#### `run` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/sampling_tool.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(self, arguments: dict[str, Any] | None = None) -> Any
+```
+
+Execute the tool with the given arguments.
+
+**Args:**
+- `arguments`: Dictionary of arguments to pass to the tool function.
+
+**Returns:**
+- The result of executing the tool function.
+
+
+#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/sampling_tool.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_function(cls, fn: Callable[..., Any]) -> SamplingTool
+```
+
+Create a SamplingTool from a function.
+
+The function's signature is analyzed to generate a JSON schema for
+the tool's parameters. Type hints are used to determine parameter types.
+
+**Args:**
+- `fn`: The function to create a tool from.
+- `name`: Optional name override. Defaults to the function's name.
+- `description`: Optional description override. Defaults to the function's docstring.
+
+**Returns:**
+- A SamplingTool wrapping the function.
+
+**Raises:**
+- `ValueError`: If the function is a lambda without a name override.
+
diff --git a/docs/python-sdk/fastmcp-server-server.mdx b/docs/python-sdk/fastmcp-server-server.mdx
index 8ab3dbc75..535d593e3 100644
--- a/docs/python-sdk/fastmcp-server-server.mdx
+++ b/docs/python-sdk/fastmcp-server-server.mdx
@@ -10,7 +10,7 @@ FastMCP - A more ergonomic interface for MCP servers.
## Functions
-### `default_lifespan` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `default_lifespan` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
default_lifespan(server: FastMCP[LifespanResultT]) -> AsyncIterator[Any]
@@ -26,255 +26,257 @@ Default lifespan context manager that does nothing.
- An empty dictionary as the lifespan result.
-### `add_resource_prefix` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2979" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-add_resource_prefix(uri: str, prefix: str) -> str
-```
-
-
-Add a prefix to a resource URI using path formatting (resource://prefix/path).
+## Classes
-**Args:**
-- `uri`: The original resource URI
-- `prefix`: The prefix to add
+### `FastMCP` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L193" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-**Returns:**
-- The resource URI with the prefix added
+**Methods:**
-**Examples:**
+#### `settings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L408" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-add_resource_prefix("resource://path/to/resource", "prefix")
-"resource://prefix/path/to/resource"
+settings(self) -> Settings
```
-With absolute path:
+
+#### `name` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L419" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
```python
-add_resource_prefix("resource:///absolute/path", "prefix")
-"resource://prefix//absolute/path"
+name(self) -> str
```
-**Raises:**
-- `ValueError`: If the URI doesn't match the expected protocol\://path format
+#### `instructions` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L423" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+```python
+instructions(self) -> str | None
+```
-### `remove_resource_prefix` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L3017" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `instructions` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L427" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-remove_resource_prefix(uri: str, prefix: str) -> str
+instructions(self, value: str | None) -> None
```
+#### `version` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-Remove a prefix from a resource URI.
+```python
+version(self) -> str | None
+```
-**Args:**
-- `uri`: The resource URI with a prefix
-- `prefix`: The prefix to remove
+#### `website_url` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-**Returns:**
-- The resource URI with the prefix removed
+```python
+website_url(self) -> str | None
+```
-**Examples:**
+#### `icons` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-remove_resource_prefix("resource://prefix/path/to/resource", "prefix")
-"resource://path/to/resource"
+icons(self) -> list[mcp.types.Icon]
```
-With absolute path:
+
+#### `docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L446" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
```python
-remove_resource_prefix("resource://prefix//absolute/path", "prefix")
-"resource:///absolute/path"
+docket(self) -> Docket | None
```
-**Raises:**
-- `ValueError`: If the URI doesn't match the expected protocol\://path format
+Get the Docket instance if Docket support is enabled.
+
+Returns None if Docket is not enabled or server hasn't been started yet.
-### `has_resource_prefix` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L3061" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `run_async` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L553" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-has_resource_prefix(uri: str, prefix: str) -> bool
+run_async(self, transport: Transport | None = None, show_banner: bool = True, **transport_kwargs: Any) -> None
```
-
-Check if a resource URI has a specific prefix.
+Run the FastMCP server asynchronously.
**Args:**
-- `uri`: The resource URI to check
-- `prefix`: The prefix to look for
+- `transport`: Transport protocol to use ("stdio", "sse", or "streamable-http")
-**Returns:**
-- True if the URI has the specified prefix, False otherwise
-**Examples:**
+#### `run` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L583" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-has_resource_prefix("resource://prefix/path/to/resource", "prefix")
-True
-```
-With other path:
-```python
-has_resource_prefix("resource://other/path/to/resource", "prefix")
-False
+run(self, transport: Transport | None = None, show_banner: bool = True, **transport_kwargs: Any) -> None
```
-**Raises:**
-- `ValueError`: If the URI doesn't match the expected protocol\://path format
-
-
-## Classes
+Run the FastMCP server. Note this is a synchronous function.
-### `FastMCP` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+**Args:**
+- `transport`: Transport protocol to use ("http", "stdio", "sse", or "streamable-http")
-**Methods:**
-#### `settings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L359" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `add_middleware` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L702" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-settings(self) -> Settings
+add_middleware(self, middleware: Middleware) -> None
```
-#### `name` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L370" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `add_provider` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L705" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-name(self) -> str
+add_provider(self, provider: Provider) -> None
```
-#### `instructions` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+Add a provider for dynamic tools, resources, and prompts.
-```python
-instructions(self) -> str | None
-```
+Providers are queried in registration order. The first provider to return
+a non-None result wins. Static components (registered via decorators)
+always take precedence over providers.
-#### `instructions` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L378" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+**Args:**
+- `provider`: A Provider instance that will provide components dynamically.
-```python
-instructions(self, value: str | None) -> None
-```
-#### `version` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L382" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `enable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L721" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-version(self) -> str | None
+enable(self) -> None
```
-#### `website_url` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L386" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-website_url(self) -> str | None
-```
+Enable components by removing from blocklist, or set allowlist with only=True.
-#### `icons` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L390" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+**Args:**
+- `keys`: Keys to enable (e.g., ``"tool\:my_tool"``).
+- `tags`: Tags to enable - components with these tags will be enabled.
+- `only`: If True, switches to allowlist mode - ONLY show these keys/tags.
+This clears existing allowlists and sets default visibility to False.
-```python
-icons(self) -> list[mcp.types.Icon]
-```
-#### `docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L397" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `disable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L756" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-docket(self) -> Docket | None
+disable(self) -> None
```
-Get the Docket instance if Docket support is enabled.
+Disable components by adding to the blocklist.
-Returns None if Docket is not enabled or server hasn't been started yet.
+**Args:**
+- `keys`: Keys to disable (e.g., ``"tool\:my_tool"``).
+- `tags`: Tags to disable - components with these tags will be disabled.
-#### `run_async` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L604" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L789" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-run_async(self, transport: Transport | None = None, show_banner: bool = True, **transport_kwargs: Any) -> None
+get_tools(self) -> dict[str, Tool]
```
-Run the FastMCP server asynchronously.
+Get all enabled tools from providers, indexed by name.
-**Args:**
-- `transport`: Transport protocol to use ("stdio", "sse", or "streamable-http")
+Iterates through all providers (LocalProvider first) and collects tools.
+First provider wins for duplicate names. Filters by server blocklist.
-#### `run` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L634" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L812" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-run(self, transport: Transport | None = None, show_banner: bool = True, **transport_kwargs: Any) -> None
+get_tool(self, name: str) -> Tool
```
-Run the FastMCP server. Note this is a synchronous function.
+Get an enabled tool by name.
-**Args:**
-- `transport`: Transport protocol to use ("stdio", "sse", or "streamable-http")
+Iterates through all providers (LocalProvider first) to find the tool.
+First provider wins. Returns only if enabled.
-#### `add_middleware` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L930" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L859" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-add_middleware(self, middleware: Middleware) -> None
+get_resources(self) -> dict[str, Resource]
```
-#### `get_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L933" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+Get all enabled resources from providers, indexed by URI.
-```python
-get_tools(self) -> dict[str, Tool]
-```
+Iterates through all providers (LocalProvider first) and collects resources.
+First provider wins for duplicate URIs. Filters by server blocklist.
-Get all tools (unfiltered), including mounted servers, indexed by key.
-
-#### `get_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L953" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L885" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-get_tool(self, key: str) -> Tool
+get_resource(self, uri: str) -> Resource
```
-#### `get_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L986" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+Get an enabled resource by URI.
+
+Iterates through all providers (LocalProvider first) to find the resource.
+First provider wins. Returns only if enabled.
+
+
+#### `get_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L901" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-get_resources(self) -> dict[str, Resource]
+get_resource_templates(self) -> dict[str, ResourceTemplate]
```
-Get all resources (unfiltered), including mounted servers, indexed by key.
+Get all enabled resource templates from providers, indexed by uri_template.
+
+Iterates through all providers (LocalProvider first) and collects templates.
+First provider wins for duplicate uri_templates. Filters by server blocklist.
-#### `get_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1017" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_resource_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L927" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-get_resource(self, key: str) -> Resource
+get_resource_template(self, uri: str) -> ResourceTemplate
```
-#### `get_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1023" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+Get an enabled resource template that matches the given URI.
+
+Iterates through all providers (LocalProvider first) to find the template.
+First provider wins. Returns only if enabled.
+
+
+#### `get_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L943" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-get_resource_templates(self) -> dict[str, ResourceTemplate]
+get_prompts(self) -> dict[str, Prompt]
```
-Get all resource templates (unfiltered), including mounted servers, indexed by key.
+Get all enabled prompts from providers, indexed by name.
+
+Iterates through all providers (LocalProvider first) and collects prompts.
+First provider wins for duplicate names. Filters by server blocklist.
-#### `get_resource_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1055" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L968" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-get_resource_template(self, key: str) -> ResourceTemplate
+get_prompt(self, name: str) -> Prompt
```
-Get a registered resource template by key.
+Get an enabled prompt by name.
+Iterates through all providers (LocalProvider first) to find the prompt.
+First provider wins. Returns only if enabled.
-#### `get_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1062" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+#### `get_component` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L984" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-get_prompts(self) -> dict[str, Prompt]
+get_component(self, key: str) -> Tool | Resource | ResourceTemplate | Prompt
```
-Get all prompts (unfiltered), including mounted servers, indexed by key.
+Get a component by its prefixed key.
+Iterates through all providers (LocalProvider first) to find the component.
+First provider wins.
-#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1082" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+**Args:**
+- `key`: The prefixed key (e.g., "tool\:name", "resource\:uri", "template\:uri").
+
+**Returns:**
+- The component if found.
+
+**Raises:**
+- `NotFoundError`: If no component is found with the given key.
-```python
-get_prompt(self, key: str) -> Prompt
-```
-#### `custom_route` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1088" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `custom_route` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1011" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
custom_route(self, path: str, methods: list[str], name: str | None = None, include_in_schema: bool = True) -> Callable[[Callable[[Request], Awaitable[Response]]], Callable[[Request], Awaitable[Response]]]
@@ -295,7 +297,7 @@ Starlette's reverse URL lookup feature)
- `include_in_schema`: Whether to include in OpenAPI schema, defaults to True
-#### `add_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1843" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `add_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1797" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
add_tool(self, tool: Tool) -> Tool
@@ -313,7 +315,7 @@ with the Context type annotation. See the @tool decorator for examples.
- The tool instance that was added to the server.
-#### `remove_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1868" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `remove_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1811" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
remove_tool(self, name: str) -> None
@@ -328,7 +330,7 @@ Remove a tool from the server.
- `NotFoundError`: If the tool is not found
-#### `add_tool_transformation` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1888" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `add_tool_transformation` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1825" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
add_tool_transformation(self, tool_name: str, transformation: ToolTransformConfig) -> None
@@ -337,7 +339,7 @@ add_tool_transformation(self, tool_name: str, transformation: ToolTransformConfi
Add a tool transformation.
-#### `remove_tool_transformation` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1894" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `remove_tool_transformation` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1831" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
remove_tool_transformation(self, tool_name: str) -> None
@@ -346,22 +348,22 @@ remove_tool_transformation(self, tool_name: str) -> None
Remove a tool transformation.
-#### `tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1899" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1836" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
tool(self, name_or_fn: AnyFunction) -> FunctionTool
```
-#### `tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1917" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1853" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
tool(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionTool]
```
-#### `tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1934" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1869" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-tool(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionTool] | FunctionTool
+tool(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionTool] | FunctionTool | partial[Callable[[AnyFunction], FunctionTool] | FunctionTool]
```
Decorator to register a tool.
@@ -385,10 +387,8 @@ This decorator supports multiple calling patterns:
- `output_schema`: Optional JSON schema for the tool's output
- `annotations`: Optional annotations about the tool's behavior
- `exclude_args`: Optional list of argument names to exclude from the tool schema.
-Note\: `exclude_args` will be deprecated in FastMCP 2.14 in favor of dependency
-injection with `Depends()` for better lifecycle management.
+Deprecated\: Use `Depends()` for dependency injection instead.
- `meta`: Optional meta information about the tool
-- `enabled`: Optional boolean to enable or disable the tool
**Examples:**
@@ -416,7 +416,7 @@ server.tool(my_function, name="custom_name")
```
-#### `add_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2079" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `add_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1954" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
add_resource(self, resource: Resource) -> Resource
@@ -431,7 +431,7 @@ Add a resource to the server.
- The resource instance that was added to the server.
-#### `add_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `add_template` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1965" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
add_template(self, template: ResourceTemplate) -> ResourceTemplate
@@ -446,7 +446,7 @@ Add a resource template to the server.
- The template instance that was added to the server.
-#### `resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L1976" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
resource(self, uri: str) -> Callable[[AnyFunction], Resource | ResourceTemplate]
@@ -473,7 +473,6 @@ has parameters, it will be registered as a template resource.
- `description`: Optional description of the resource
- `mime_type`: Optional MIME type for the resource
- `tags`: Optional set of tags for categorizing the resource
-- `enabled`: Optional boolean to enable or disable the resource
- `annotations`: Optional annotations about the resource's behavior
- `meta`: Optional meta information about the resource
@@ -506,7 +505,7 @@ async def get_weather(city: str) -> str:
```
-#### `add_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2268" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `add_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2060" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
add_prompt(self, prompt: Prompt) -> Prompt
@@ -521,22 +520,22 @@ Add a prompt to the server.
- The prompt instance that was added to the server.
-#### `prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2291" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2072" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
prompt(self, name_or_fn: AnyFunction) -> FunctionPrompt
```
-#### `prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2306" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2086" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
prompt(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionPrompt]
```
-#### `prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2320" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2099" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-prompt(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt
+prompt(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt | partial[Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt]
```
Decorator to register a prompt.
@@ -557,7 +556,6 @@ Decorator to register a prompt.
name: Optional name for the prompt (keyword-only, alternative to name_or_fn)
description: Optional description of what the prompt does
tags: Optional set of tags for categorizing the prompt
- enabled: Optional boolean to enable or disable the prompt
meta: Optional meta information about the prompt
Examples:
@@ -611,7 +609,7 @@ Decorator to register a prompt.
```
-#### `run_stdio_async` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2472" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `run_stdio_async` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
run_stdio_async(self, show_banner: bool = True, log_level: str | None = None) -> None
@@ -624,7 +622,7 @@ Run the server using stdio transport.
- `log_level`: Log level for the server
-#### `run_http_async` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2509" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `run_http_async` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
run_http_async(self, show_banner: bool = True, transport: Literal['http', 'streamable-http', 'sse'] = 'http', host: str | None = None, port: int | None = None, log_level: str | None = None, path: str | None = None, uvicorn_config: dict[str, Any] | None = None, middleware: list[ASGIMiddleware] | None = None, json_response: bool | None = None, stateless_http: bool | None = None) -> None
@@ -644,7 +642,7 @@ Run the server using HTTP transport.
- `stateless_http`: Whether to use stateless HTTP (defaults to settings.stateless_http)
-#### `http_app` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2588" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `http_app` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
http_app(self, path: str | None = None, middleware: list[ASGIMiddleware] | None = None, json_response: bool | None = None, stateless_http: bool | None = None, transport: Literal['http', 'streamable-http', 'sse'] = 'http', event_store: EventStore | None = None, retry_interval: int | None = None) -> StarletteWithLifespan
@@ -670,13 +668,13 @@ streamable-http transport.
- A Starlette application configured with the specified transport
-#### `mount` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2649" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `mount` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2372" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-mount(self, server: FastMCP[LifespanResultT], prefix: str | None = None, as_proxy: bool | None = None) -> None
+mount(self, server: FastMCP[LifespanResultT], namespace: str | None = None, as_proxy: bool | None = None, tool_names: dict[str, str] | None = None, prefix: str | None = None) -> None
```
-Mount another FastMCP server on this server with an optional prefix.
+Mount another FastMCP server on this server with an optional namespace.
Unlike importing (with import_server), mounting establishes a dynamic connection
between servers. When a client interacts with a mounted server's objects through
@@ -684,44 +682,40 @@ the parent server, requests are forwarded to the mounted server in real-time.
This means changes to the mounted server are immediately reflected when accessed
through the parent.
-When a server is mounted with a prefix:
-- Tools from the mounted server are accessible with prefixed names.
- Example: If server has a tool named "get_weather", it will be available as "prefix_get_weather".
-- Resources are accessible with prefixed URIs.
+When a server is mounted with a namespace:
+- Tools from the mounted server are accessible with namespaced names.
+ Example: If server has a tool named "get_weather", it will be available as "namespace_get_weather".
+- Resources are accessible with namespaced URIs.
Example: If server has a resource with URI "weather://forecast", it will be available as
- "weather://prefix/forecast".
-- Templates are accessible with prefixed URI templates.
+ "weather://namespace/forecast".
+- Templates are accessible with namespaced URI templates.
Example: If server has a template with URI "weather://location/{id}", it will be available
- as "weather://prefix/location/{id}".
-- Prompts are accessible with prefixed names.
+ as "weather://namespace/location/{id}".
+- Prompts are accessible with namespaced names.
Example: If server has a prompt named "weather_prompt", it will be available as
- "prefix_weather_prompt".
+ "namespace_weather_prompt".
-When a server is mounted without a prefix (prefix=None), its tools, resources, templates,
+When a server is mounted without a namespace (namespace=None), its tools, resources, templates,
and prompts are accessible with their original names. Multiple servers can be mounted
-without prefixes, and they will be tried in order until a match is found.
+without namespaces, and they will be tried in order until a match is found.
-There are two modes for mounting servers:
-1. Direct mounting (default when server has no custom lifespan): The parent server
- directly accesses the mounted server's objects in-memory for better performance.
- In this mode, no client lifecycle events occur on the mounted server, including
- lifespan execution.
-
-2. Proxy mounting (default when server has a custom lifespan): The parent server
- treats the mounted server as a separate entity and communicates with it via a
- Client transport. This preserves all client-facing behaviors, including lifespan
- execution, but with slightly higher overhead.
+The mounted server's lifespan is executed when the parent server starts, and its
+middleware chain is invoked for all operations (tool calls, resource reads, prompts).
**Args:**
- `server`: The FastMCP server to mount.
-- `prefix`: Optional prefix to use for the mounted server's objects. If None,
+- `namespace`: Optional namespace to use for the mounted server's objects. If None,
the server's objects are accessible with their original names.
-- `as_proxy`: Whether to treat the mounted server as a proxy. If None (default),
-automatically determined based on whether the server has a custom lifespan
-(True if it has a custom lifespan, False otherwise).
+- `as_proxy`: Deprecated. Mounted servers now always have their lifespan and
+middleware invoked. To create a proxy server, use FastMCP.as_proxy()
+explicitly before mounting.
+- `tool_names`: Optional mapping of original tool names to custom names. Use this
+to override namespaced names. Keys are the original tool names from the
+mounted server.
+- `prefix`: Deprecated. Use namespace instead.
-#### `import_server` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2721" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `import_server` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2459" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
import_server(self, server: FastMCP[LifespanResultT], prefix: str | None = None) -> None
@@ -730,6 +724,10 @@ import_server(self, server: FastMCP[LifespanResultT], prefix: str | None = None)
Import the MCP objects from another FastMCP server into this one,
optionally with a given prefix.
+.. deprecated::
+ Use :meth:`mount` instead. ``import_server`` will be removed in a
+ future version.
+
Note that when a server is *imported*, its objects are immediately
registered to the importing server. This is a one-time operation and
future changes to the imported server will not be reflected in the
@@ -758,25 +756,55 @@ templates, and prompts are imported with their original names.
objects are imported with their original names.
-#### `from_openapi` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2803" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `from_openapi` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2559" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-from_openapi(cls, openapi_spec: dict[str, Any], client: httpx.AsyncClient, route_maps: list[RouteMap] | None = None, route_map_fn: OpenAPIRouteMapFn | None = None, mcp_component_fn: OpenAPIComponentFn | None = None, mcp_names: dict[str, str] | None = None, tags: set[str] | None = None, **settings: Any) -> FastMCPOpenAPI
+from_openapi(cls, openapi_spec: dict[str, Any], client: httpx.AsyncClient, name: str = 'OpenAPI Server', route_maps: list[RouteMap] | None = None, route_map_fn: OpenAPIRouteMapFn | None = None, mcp_component_fn: OpenAPIComponentFn | None = None, mcp_names: dict[str, str] | None = None, tags: set[str] | None = None, timeout: float | None = None, **settings: Any) -> Self
```
Create a FastMCP server from an OpenAPI specification.
+**Args:**
+- `openapi_spec`: OpenAPI schema as a dictionary
+- `client`: httpx AsyncClient for making HTTP requests
+- `name`: Name for the MCP server
+- `route_maps`: Optional list of RouteMap objects defining route mappings
+- `route_map_fn`: Optional callable for advanced route type mapping
+- `mcp_component_fn`: Optional callable for component customization
+- `mcp_names`: Optional dictionary mapping operationId to component names
+- `tags`: Optional set of tags to add to all components
+- `timeout`: Optional timeout (in seconds) for all requests
+- `**settings`: Additional settings passed to FastMCP
-#### `from_fastapi` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2831" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+**Returns:**
+- A FastMCP server with an OpenAPIProvider attached.
+
+
+#### `from_fastapi` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-from_fastapi(cls, app: Any, name: str | None = None, route_maps: list[RouteMap] | None = None, route_map_fn: OpenAPIRouteMapFn | None = None, mcp_component_fn: OpenAPIComponentFn | None = None, mcp_names: dict[str, str] | None = None, httpx_client_kwargs: dict[str, Any] | None = None, tags: set[str] | None = None, **settings: Any) -> FastMCPOpenAPI
+from_fastapi(cls, app: Any, name: str | None = None, route_maps: list[RouteMap] | None = None, route_map_fn: OpenAPIRouteMapFn | None = None, mcp_component_fn: OpenAPIComponentFn | None = None, mcp_names: dict[str, str] | None = None, httpx_client_kwargs: dict[str, Any] | None = None, tags: set[str] | None = None, timeout: float | None = None, **settings: Any) -> Self
```
Create a FastMCP server from a FastAPI application.
+**Args:**
+- `app`: FastAPI application instance
+- `name`: Name for the MCP server (defaults to app.title)
+- `route_maps`: Optional list of RouteMap objects defining route mappings
+- `route_map_fn`: Optional callable for advanced route type mapping
+- `mcp_component_fn`: Optional callable for component customization
+- `mcp_names`: Optional dictionary mapping operationId to component names
+- `httpx_client_kwargs`: Optional kwargs passed to httpx.AsyncClient
+- `tags`: Optional set of tags to add to all components
+- `timeout`: Optional timeout (in seconds) for all requests
+- `**settings`: Additional settings passed to FastMCP
-#### `as_proxy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2872" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+**Returns:**
+- A FastMCP server with an OpenAPIProvider attached.
+
+
+#### `as_proxy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2662" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
as_proxy(cls, backend: Client[ClientTransportT] | ClientTransport | FastMCP[Any] | FastMCP1Server | AnyUrl | Path | MCPConfig | dict[str, Any] | str, **settings: Any) -> FastMCPProxy
@@ -790,10 +818,8 @@ instance or any value accepted as the `transport` argument of
`fastmcp.client.Client` constructor.
-#### `generate_name` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2964" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `generate_name` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2723" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
generate_name(cls, name: str | None = None) -> str
```
-
-### `MountedServer` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/server.py#L2974" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
diff --git a/docs/python-sdk/fastmcp-server-tasks-config.mdx b/docs/python-sdk/fastmcp-server-tasks-config.mdx
index cac8b9254..01ceba275 100644
--- a/docs/python-sdk/fastmcp-server-tasks-config.mdx
+++ b/docs/python-sdk/fastmcp-server-tasks-config.mdx
@@ -14,7 +14,7 @@ handle task-augmented execution as specified in SEP-1686.
## Classes
-### `TaskConfig` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/config.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `TaskConfig` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/config.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Configuration for MCP background task execution (SEP-1686).
@@ -31,7 +31,7 @@ Controls how a component handles task-augmented requests:
**Methods:**
-#### `from_bool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/config.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `from_bool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/config.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
from_bool(cls, value: bool) -> TaskConfig
@@ -46,7 +46,19 @@ Convert boolean task flag to TaskConfig.
- TaskConfig with appropriate mode.
-#### `validate_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/config.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `supports_tasks` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/config.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+supports_tasks(self) -> bool
+```
+
+Check if this component supports task execution.
+
+**Returns:**
+- True if mode is "optional" or "required", False if "forbidden".
+
+
+#### `validate_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/config.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
validate_function(self, fn: Callable[..., Any], name: str) -> None
diff --git a/docs/python-sdk/fastmcp-server-tasks-converters.mdx b/docs/python-sdk/fastmcp-server-tasks-converters.mdx
deleted file mode 100644
index 94118c394..000000000
--- a/docs/python-sdk/fastmcp-server-tasks-converters.mdx
+++ /dev/null
@@ -1,77 +0,0 @@
----
-title: converters
-sidebarTitle: converters
----
-
-# `fastmcp.server.tasks.converters`
-
-
-SEP-1686 task result converters.
-
-Converts raw task return values to MCP result types.
-
-
-## Functions
-
-### `convert_tool_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/converters.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-convert_tool_result(server: FastMCP, raw_value: Any, tool_name: str, client_task_id: str) -> mcp.types.CallToolResult
-```
-
-
-Convert raw tool return value to MCP CallToolResult.
-
-Replicates the serialization logic from tool.run() to properly handle
-output_schema, structured content, etc.
-
-**Args:**
-- `server`: FastMCP server instance
-- `raw_value`: The raw return value from user's tool function
-- `tool_name`: Name of the tool (to get output_schema and serializer)
-- `client_task_id`: Client task ID for related-task metadata
-
-**Returns:**
-- CallToolResult with properly formatted content and structured content
-
-
-### `convert_prompt_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/converters.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-convert_prompt_result(server: FastMCP, raw_value: Any, prompt_name: str, client_task_id: str) -> mcp.types.GetPromptResult
-```
-
-
-Convert raw prompt return value to MCP GetPromptResult.
-
-The user function returns raw values (strings, dicts, lists) that need
-to be converted to PromptMessage objects.
-
-**Args:**
-- `server`: FastMCP server instance
-- `raw_value`: The raw return value from user's prompt function
-- `prompt_name`: Name of the prompt
-- `client_task_id`: Client task ID for related-task metadata
-
-**Returns:**
-- GetPromptResult with properly formatted messages
-
-
-### `convert_resource_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/converters.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-convert_resource_result(server: FastMCP, raw_value: Any, uri: str, client_task_id: str) -> dict[str, Any]
-```
-
-
-Convert raw resource return value to MCP resource contents dict.
-
-**Args:**
-- `server`: FastMCP server instance
-- `raw_value`: The raw return value from user's resource function (str or bytes)
-- `uri`: Resource URI (for the contents response)
-- `client_task_id`: Client task ID for related-task metadata
-
-**Returns:**
-- Dict with 'contents' key containing list of resource contents
-
diff --git a/docs/python-sdk/fastmcp-server-tasks-handlers.mdx b/docs/python-sdk/fastmcp-server-tasks-handlers.mdx
index 423f3bdea..e633a193c 100644
--- a/docs/python-sdk/fastmcp-server-tasks-handlers.mdx
+++ b/docs/python-sdk/fastmcp-server-tasks-handlers.mdx
@@ -13,66 +13,31 @@ Handles queuing tool/prompt/resource executions to Docket as background tasks.
## Functions
-### `handle_tool_as_task` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/handlers.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `submit_to_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/handlers.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-handle_tool_as_task(server: FastMCP, tool_name: str, arguments: dict[str, Any], task_meta: dict[str, Any]) -> mcp.types.CallToolResult
+submit_to_docket(task_type: Literal['tool', 'resource', 'template', 'prompt'], key: str, component: Tool | Resource | ResourceTemplate | Prompt, arguments: dict[str, Any] | None = None) -> mcp.types.CreateTaskResult
```
-Handle tool execution as background task (SEP-1686).
+Submit any component to Docket for background execution (SEP-1686).
-Queues the user's actual function to Docket (preserving signature for DI),
-stores raw return values, converts to MCP types on retrieval.
+Unified handler for all component types. Called by component's internal
+methods (_run, _read, _render) when task metadata is present and mode allows.
-**Args:**
-- `server`: FastMCP server instance
-- `tool_name`: Name of the tool to execute
-- `arguments`: Tool arguments
-- `task_meta`: Task metadata from request (contains ttl)
-
-**Returns:**
-- Task stub with task metadata in _meta
-
-
-### `handle_prompt_as_task` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/handlers.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-handle_prompt_as_task(server: FastMCP, prompt_name: str, arguments: dict[str, Any] | None, task_meta: dict[str, Any]) -> mcp.types.GetPromptResult
-```
-
-
-Handle prompt execution as background task (SEP-1686).
-
-Queues the user's actual function to Docket (preserving signature for DI).
-
-**Args:**
-- `server`: FastMCP server instance
-- `prompt_name`: Name of the prompt to execute
-- `arguments`: Prompt arguments
-- `task_meta`: Task metadata from request (contains ttl)
-
-**Returns:**
-- Task stub with task metadata in _meta
-
-
-### `handle_resource_as_task` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/handlers.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-handle_resource_as_task(server: FastMCP, uri: str, resource, task_meta: dict[str, Any]) -> mcp.types.ServerResult
-```
-
-
-Handle resource read as background task (SEP-1686).
+Queues the component's method to Docket, stores raw return values,
+and converts to MCP types on retrieval.
-Queues the user's actual function to Docket.
+Note: Client-requested TTL in task_meta is intentionally ignored.
+Server-side TTL policy (docket.execution_ttl) takes precedence for
+consistent task lifecycle management.
**Args:**
-- `server`: FastMCP server instance
-- `uri`: Resource URI
-- `resource`: Resource or ResourceTemplate object
-- `task_meta`: Task metadata from request (contains ttl)
+- `task_type`: Component type for task key construction
+- `key`: The component key as seen by MCP layer (with namespace prefix)
+- `component`: The component instance (Tool, Resource, ResourceTemplate, Prompt)
+- `arguments`: Arguments/params (None for Resource which has no args)
**Returns:**
-- ServerResult with ReadResourceResult stub
+- Task stub with proper Task object
diff --git a/docs/python-sdk/fastmcp-server-tasks-protocol.mdx b/docs/python-sdk/fastmcp-server-tasks-requests.mdx
similarity index 75%
rename from docs/python-sdk/fastmcp-server-tasks-protocol.mdx
rename to docs/python-sdk/fastmcp-server-tasks-requests.mdx
index 6d355b824..912fc9cc5 100644
--- a/docs/python-sdk/fastmcp-server-tasks-protocol.mdx
+++ b/docs/python-sdk/fastmcp-server-tasks-requests.mdx
@@ -1,19 +1,20 @@
---
-title: protocol
-sidebarTitle: protocol
+title: requests
+sidebarTitle: requests
---
-# `fastmcp.server.tasks.protocol`
+# `fastmcp.server.tasks.requests`
-SEP-1686 task protocol handlers.
+SEP-1686 task request handlers.
-Implements MCP task protocol methods: tasks/get, tasks/result, tasks/list, tasks/cancel, tasks/delete.
+Handles MCP task protocol requests: tasks/get, tasks/result, tasks/list, tasks/cancel.
+These handlers query and manage existing tasks (contrast with handlers.py which creates tasks).
## Functions
-### `tasks_get_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/protocol.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `tasks_get_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/requests.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
tasks_get_handler(server: FastMCP, params: dict[str, Any]) -> GetTaskResult
@@ -30,7 +31,7 @@ Handle MCP 'tasks/get' request (SEP-1686).
- Task status response with spec-compliant fields
-### `tasks_result_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/protocol.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `tasks_result_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/requests.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
tasks_result_handler(server: FastMCP, params: dict[str, Any]) -> Any
@@ -49,7 +50,7 @@ Converts raw task return values to MCP types based on task type.
- MCP result (CallToolResult, GetPromptResult, or ReadResourceResult)
-### `tasks_list_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/protocol.py#L256" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `tasks_list_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/requests.py#L352" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
tasks_list_handler(server: FastMCP, params: dict[str, Any]) -> ListTasksResult
@@ -68,7 +69,7 @@ Note: With client-side tracking, this returns minimal info.
- Response with tasks list and pagination
-### `tasks_cancel_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/protocol.py#L274" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `tasks_cancel_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/requests.py#L370" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
tasks_cancel_handler(server: FastMCP, params: dict[str, Any]) -> CancelTaskResult
diff --git a/docs/python-sdk/fastmcp-server-tasks-routing.mdx b/docs/python-sdk/fastmcp-server-tasks-routing.mdx
new file mode 100644
index 000000000..7402e77ff
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-tasks-routing.mdx
@@ -0,0 +1,37 @@
+---
+title: routing
+sidebarTitle: routing
+---
+
+# `fastmcp.server.tasks.routing`
+
+
+Task routing helper for MCP components.
+
+Provides unified task mode enforcement and docket routing logic.
+
+
+## Functions
+
+### `check_background_task` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/routing.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+check_background_task(component: Tool | Resource | ResourceTemplate | Prompt, task_type: TaskType, key: str, arguments: dict[str, Any] | None = None) -> mcp.types.CreateTaskResult | None
+```
+
+
+Check task mode and submit to background if requested.
+
+**Args:**
+- `component`: The MCP component
+- `task_type`: Type of task ("tool", "resource", "template", "prompt")
+- `key`: Docket registration key (caller resolves from contextvar + fallback)
+- `arguments`: Arguments for tool/prompt/template execution
+
+**Returns:**
+- CreateTaskResult if submitted to docket, None for sync execution
+
+**Raises:**
+- `McpError`: If mode="required" but no task metadata, or mode="forbidden"
+ but task metadata is present
+
diff --git a/docs/python-sdk/fastmcp-server-tasks-subscriptions.mdx b/docs/python-sdk/fastmcp-server-tasks-subscriptions.mdx
index 78f06cf81..1b4331212 100644
--- a/docs/python-sdk/fastmcp-server-tasks-subscriptions.mdx
+++ b/docs/python-sdk/fastmcp-server-tasks-subscriptions.mdx
@@ -17,7 +17,7 @@ to clients when their tasks change state.
### `subscribe_to_task_updates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/tasks/subscriptions.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-subscribe_to_task_updates(task_id: str, task_key: str, session: ServerSession, docket: Docket) -> None
+subscribe_to_task_updates(task_id: str, task_key: str, session: ServerSession, docket: Docket, poll_interval_ms: int = 5000) -> None
```
@@ -32,4 +32,5 @@ client polling frequency.
- `task_key`: Internal Docket execution key (includes session, type, component)
- `session`: MCP ServerSession for sending notifications
- `docket`: Docket instance for subscribing to execution events
+- `poll_interval_ms`: Poll interval in milliseconds to include in notifications
diff --git a/docs/python-sdk/fastmcp-tools-tool.mdx b/docs/python-sdk/fastmcp-tools-tool.mdx
index d6fc3accc..141e4c942 100644
--- a/docs/python-sdk/fastmcp-tools-tool.mdx
+++ b/docs/python-sdk/fastmcp-tools-tool.mdx
@@ -7,7 +7,7 @@ sidebarTitle: tool
## Functions
-### `default_serializer` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `default_serializer` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
default_serializer(data: Any) -> str
@@ -15,17 +15,17 @@ default_serializer(data: Any) -> str
## Classes
-### `ToolResult` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ToolResult` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
**Methods:**
-#### `to_mcp_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `to_mcp_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
to_mcp_result(self) -> list[ContentBlock] | tuple[list[ContentBlock], dict[str, Any]] | CallToolResult
```
-### `Tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `Tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Internal tool registration info.
@@ -33,19 +33,7 @@ Internal tool registration info.
**Methods:**
-#### `enable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L151" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-enable(self) -> None
-```
-
-#### `disable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-disable(self) -> None
-```
-
-#### `to_mcp_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `to_mcp_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
to_mcp_tool(self, **overrides: Any) -> MCPTool
@@ -54,16 +42,16 @@ to_mcp_tool(self, **overrides: Any) -> MCPTool
Convert the FastMCP tool to an MCP tool.
-#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L186" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-from_function(fn: Callable[..., Any], name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, tags: set[str] | None = None, annotations: ToolAnnotations | None = None, exclude_args: list[str] | None = None, output_schema: dict[str, Any] | NotSetT | None = NotSet, serializer: ToolResultSerializerType | None = None, meta: dict[str, Any] | None = None, enabled: bool | None = None, task: bool | TaskConfig | None = None) -> FunctionTool
+from_function(fn: Callable[..., Any], name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, tags: set[str] | None = None, annotations: ToolAnnotations | None = None, exclude_args: list[str] | None = None, output_schema: dict[str, Any] | NotSetT | None = NotSet, serializer: ToolResultSerializerType | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionTool
```
Create a Tool from a function.
-#### `run` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `run` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L216" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
run(self, arguments: dict[str, Any]) -> ToolResult
@@ -78,17 +66,54 @@ implemented by subclasses.
(list of ContentBlocks, dict of structured output).
-#### `from_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L241" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `convert_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+convert_result(self, raw_value: Any) -> ToolResult
+```
+
+Convert a raw result to ToolResult.
+
+Handles ToolResult passthrough and converts raw values using the tool's
+attributes (serializer, output_schema) for proper conversion.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L293" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this tool with docket for background execution.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L299" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, arguments: dict[str, Any], **kwargs: Any) -> Execution
+```
+
+Schedule this tool for background execution via docket.
+
+**Args:**
+- `docket`: The Docket instance
+- `arguments`: Tool arguments
+- `fn_key`: Function lookup key in Docket registry (defaults to self.key)
+- `task_key`: Redis storage key for the result
+- `**kwargs`: Additional kwargs passed to docket.add()
+
+
+#### `from_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
from_tool(cls, tool: Tool) -> TransformedTool
```
-### `FunctionTool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L275" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `FunctionTool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L355" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
**Methods:**
-#### `to_mcp_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L282" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `to_mcp_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
to_mcp_tool(self, **overrides: Any) -> MCPTool
@@ -99,16 +124,16 @@ Convert the FastMCP tool to an MCP tool.
Extends the base implementation to add task execution mode if enabled.
-#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-from_function(cls, fn: Callable[..., Any], name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, tags: set[str] | None = None, annotations: ToolAnnotations | None = None, exclude_args: list[str] | None = None, output_schema: dict[str, Any] | NotSetT | None = NotSet, serializer: ToolResultSerializerType | None = None, meta: dict[str, Any] | None = None, enabled: bool | None = None, task: bool | TaskConfig | None = None) -> FunctionTool
+from_function(cls, fn: Callable[..., Any], name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, tags: set[str] | None = None, annotations: ToolAnnotations | None = None, exclude_args: list[str] | None = None, output_schema: dict[str, Any] | NotSetT | None = NotSet, serializer: ToolResultSerializerType | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionTool
```
Create a Tool from a function.
-#### `run` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L379" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `run` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L451" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
run(self, arguments: dict[str, Any]) -> ToolResult
@@ -117,11 +142,41 @@ run(self, arguments: dict[str, Any]) -> ToolResult
Run the tool with arguments.
-### `ParsedFunction` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L438" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `register_with_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L461" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this tool with docket for background execution.
+
+FunctionTool registers the underlying function, which has the user's
+Depends parameters for docket to resolve.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L471" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, arguments: dict[str, Any], **kwargs: Any) -> Execution
+```
+
+Schedule this tool for background execution via docket.
+
+FunctionTool splats the arguments dict since .fn expects **kwargs.
+
+**Args:**
+- `docket`: The Docket instance
+- `arguments`: Tool arguments
+- `fn_key`: Function lookup key in Docket registry (defaults to self.key)
+- `task_key`: Redis storage key for the result
+- `**kwargs`: Additional kwargs passed to docket.add()
+
+
+### `ParsedFunction` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L513" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
**Methods:**
-#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L446" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `from_function` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py#L521" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
from_function(cls, fn: Callable[..., Any], exclude_args: list[str] | None = None, validate: bool = True, wrap_non_object_output_schema: bool = True) -> ParsedFunction
diff --git a/docs/python-sdk/fastmcp-tools-tool_manager.mdx b/docs/python-sdk/fastmcp-tools-tool_manager.mdx
deleted file mode 100644
index 592b18d58..000000000
--- a/docs/python-sdk/fastmcp-tools-tool_manager.mdx
+++ /dev/null
@@ -1,113 +0,0 @@
----
-title: tool_manager
-sidebarTitle: tool_manager
----
-
-# `fastmcp.tools.tool_manager`
-
-## Classes
-
-### `ToolManager` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_manager.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-Manages FastMCP tools.
-
-
-**Methods:**
-
-#### `has_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_manager.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-has_tool(self, key: str) -> bool
-```
-
-Check if a tool exists.
-
-
-#### `get_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_manager.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-get_tool(self, key: str) -> Tool
-```
-
-Get tool by key.
-
-
-#### `get_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_manager.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-get_tools(self) -> dict[str, Tool]
-```
-
-Gets the complete, unfiltered inventory of local tools.
-
-
-#### `add_tool_from_fn` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_manager.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-add_tool_from_fn(self, fn: Callable[..., Any], name: str | None = None, description: str | None = None, tags: set[str] | None = None, annotations: ToolAnnotations | None = None, serializer: Callable[[Any], str] | None = None, exclude_args: list[str] | None = None) -> Tool
-```
-
-Add a tool to the server.
-
-
-#### `add_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_manager.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-add_tool(self, tool: Tool) -> Tool
-```
-
-Register a tool with the server.
-
-
-#### `add_tool_transformation` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_manager.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-add_tool_transformation(self, tool_name: str, transformation: ToolTransformConfig) -> None
-```
-
-Add a tool transformation.
-
-
-#### `get_tool_transformation` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_manager.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-get_tool_transformation(self, tool_name: str) -> ToolTransformConfig | None
-```
-
-Get a tool transformation.
-
-
-#### `remove_tool_transformation` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_manager.py#L134" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-remove_tool_transformation(self, tool_name: str) -> None
-```
-
-Remove a tool transformation.
-
-
-#### `remove_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_manager.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-remove_tool(self, key: str) -> None
-```
-
-Remove a tool from the server.
-
-**Args:**
-- `key`: The key of the tool to remove
-
-**Raises:**
-- `NotFoundError`: If the tool is not found
-
-
-#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_manager.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-```python
-call_tool(self, key: str, arguments: dict[str, Any]) -> ToolResult
-```
-
-Internal API for servers: Finds and calls a tool, respecting the
-filtered protocol path.
-
diff --git a/docs/python-sdk/fastmcp-tools-tool_transform.mdx b/docs/python-sdk/fastmcp-tools-tool_transform.mdx
index 8586fb4fc..ba171fcb7 100644
--- a/docs/python-sdk/fastmcp-tools-tool_transform.mdx
+++ b/docs/python-sdk/fastmcp-tools-tool_transform.mdx
@@ -62,7 +62,7 @@ y=2)` will call the parent tool with `x=1` and `y=2`.
- `RuntimeError`: If called outside a transformed tool context.
-### `apply_transformations_to_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L924" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `apply_transformations_to_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L916" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
apply_transformations_to_tools(tools: dict[str, Tool], transformations: dict[str, ToolTransformConfig]) -> dict[str, Tool]
@@ -72,6 +72,9 @@ apply_transformations_to_tools(tools: dict[str, Tool], transformations: dict[str
Apply a list of transformations to a list of tools. Tools that do not have any transformations
are left unchanged.
+Note: tools dict is keyed by prefixed key (e.g., "tool:my_tool"),
+but transformations are keyed by tool name (e.g., "my_tool").
+
## Classes
@@ -84,6 +87,16 @@ This class allows fine-grained control over how individual arguments are transfo
when creating a new tool from an existing one. You can rename arguments, change their
descriptions, add default values, or hide them from clients while passing constants.
+**Attributes:**
+- `name`: New name for the argument. Use None to keep original name, or ... for no change.
+- `description`: New description for the argument. Use None to remove description, or ... for no change.
+- `default`: New default value for the argument. Use ... for no change.
+- `default_factory`: Callable that returns a default value. Cannot be used with default.
+- `type`: New type for the argument. Use ... for no change.
+- `hide`: If True, hide this argument from clients but pass a constant value to parent.
+- `required`: If True, make argument required (remove default). Use ... for no change.
+- `examples`: Examples for the argument. Use ... for no change.
+
**Examples:**
Rename argument 'old_name' to 'new_name'
@@ -168,6 +181,13 @@ or can include a custom function that uses forward() to call the parent tool
with transformed arguments. Output schemas and structured outputs are automatically
inherited from the parent tool but can be overridden or disabled.
+**Attributes:**
+- `parent_tool`: The original tool that this tool was transformed from.
+- `fn`: The function to execute when this tool is called (either the forwarding
+function for pure transformations or a custom user function).
+- `forwarding_fn`: Internal function that handles argument transformation and
+validation when forward() is called from custom functions.
+
**Methods:**
@@ -193,7 +213,7 @@ functions.
#### `from_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L363" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-from_tool(cls, tool: Tool, name: str | None = None, title: str | NotSetT | None = NotSet, description: str | NotSetT | None = NotSet, tags: set[str] | None = None, transform_fn: Callable[..., Any] | None = None, transform_args: dict[str, ArgTransform] | None = None, annotations: ToolAnnotations | NotSetT | None = NotSet, output_schema: dict[str, Any] | NotSetT | None = NotSet, serializer: Callable[[Any], str] | NotSetT | None = NotSet, meta: dict[str, Any] | NotSetT | None = NotSet, enabled: bool | None = None) -> TransformedTool
+from_tool(cls, tool: Tool, name: str | None = None, title: str | NotSetT | None = NotSet, description: str | NotSetT | None = NotSet, tags: set[str] | None = None, transform_fn: Callable[..., Any] | None = None, transform_args: dict[str, ArgTransform] | None = None, annotations: ToolAnnotations | NotSetT | None = NotSet, output_schema: dict[str, Any] | NotSetT | None = NotSet, serializer: Callable[[Any], str] | NotSetT | None = NotSet, meta: dict[str, Any] | NotSetT | None = NotSet) -> TransformedTool
```
Create a transformed tool from a parent tool.
@@ -272,7 +292,7 @@ async def custom_output(**kwargs) -> ToolResult:
```
-### `ToolTransformConfig` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L878" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ToolTransformConfig` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L875" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Provides a way to transform a tool.
@@ -280,7 +300,7 @@ Provides a way to transform a tool.
**Methods:**
-#### `apply` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L910" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `apply` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L902" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
apply(self, tool: Tool) -> TransformedTool
diff --git a/docs/python-sdk/fastmcp-utilities-components.mdx b/docs/python-sdk/fastmcp-utilities-components.mdx
index d27c20282..08879acdf 100644
--- a/docs/python-sdk/fastmcp-utilities-components.mdx
+++ b/docs/python-sdk/fastmcp-utilities-components.mdx
@@ -7,9 +7,9 @@ sidebarTitle: components
## Classes
-### `FastMCPMeta` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `FastMCPMeta` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-### `FastMCPComponent` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `FastMCPComponent` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Base class for FastMCP tools, prompts, resources, and resource templates.
@@ -17,63 +17,66 @@ Base class for FastMCP tools, prompts, resources, and resource templates.
**Methods:**
-#### `key` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `make_key` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-key(self) -> str
+make_key(cls, identifier: str) -> str
```
-The key of the component. This is used for internal bookkeeping
-and may reflect e.g. prefixes or other identifiers. You should not depend on
-keys having a certain value, as the same tool loaded from different
-hierarchies of servers may have different keys.
+Construct the lookup key for this component type.
+
+**Args:**
+- `identifier`: The raw identifier (name for tools/prompts, uri for resources)
+
+**Returns:**
+- A prefixed key like "tool:name" or "resource:uri"
-#### `get_meta` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `key` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-get_meta(self, include_fastmcp_meta: bool | None = None) -> dict[str, Any] | None
+key(self) -> str
```
-Get the meta information about the component.
+The globally unique lookup key for this component.
-If include_fastmcp_meta is True, a `_fastmcp` key will be added to the
-meta, containing a `tags` field with the tags of the component.
+Format: "{key_prefix}:{identifier}" e.g. "tool:my_tool", "resource:file://x.txt"
+
+Subclasses should override this to use their specific identifier.
+Base implementation uses name.
-#### `model_copy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_meta` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-model_copy(self) -> Self
+get_meta(self, include_fastmcp_meta: bool | None = None) -> dict[str, Any] | None
```
-Create a copy of the component.
+Get the meta information about the component.
-**Args:**
-- `update`: A dictionary of fields to update.
-- `deep`: Whether to deep copy the component.
-- `key`: The key to use for the copy.
+If include_fastmcp_meta is True, a `_fastmcp` key will be added to the
+meta, containing a `tags` field with the tags of the component.
-#### `enable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `enable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
enable(self) -> None
```
-Enable the component.
+Removed in 3.0. Use server.enable(keys=[...]) instead.
-#### `disable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `disable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
disable(self) -> None
```
-Disable the component.
+Removed in 3.0. Use server.disable(keys=[...]) instead.
-#### `copy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `copy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
copy(self) -> Self
@@ -82,40 +85,31 @@ copy(self) -> Self
Create a copy of the component.
-### `MirroredComponent` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
-
-
-Base class for components that are mirrored from a remote server.
-
-Mirrored components cannot be enabled or disabled directly. Call copy() first
-to create a local version you can modify.
-
-
-**Methods:**
-
-#### `enable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `register_with_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-enable(self) -> None
+register_with_docket(self, docket: Docket) -> None
```
-Enable the component.
+Register this component with docket for background execution.
+No-ops if task_config.mode is "forbidden". Subclasses override to
+register their callable (self.run, self.read, self.render, or self.fn).
-#### `disable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+#### `add_to_docket` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
-disable(self) -> None
+add_to_docket(self, docket: Docket, *args: Any, **kwargs: Any) -> Execution
```
-Disable the component.
-
-
-#### `copy` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/components.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+Schedule this component for background execution via docket.
-```python
-copy(self) -> Self
-```
+Subclasses override this to handle their specific calling conventions:
+- Tool: add_to_docket(docket, arguments: dict, **kwargs)
+- Resource: add_to_docket(docket, **kwargs)
+- ResourceTemplate: add_to_docket(docket, params: dict, **kwargs)
+- Prompt: add_to_docket(docket, arguments: dict | None, **kwargs)
-Create a copy of the component that can be modified.
+The **kwargs are passed through to docket.add() (e.g., key=task_key).
diff --git a/docs/python-sdk/fastmcp-utilities-inspect.mdx b/docs/python-sdk/fastmcp-utilities-inspect.mdx
index ab1c8744c..01bc77b39 100644
--- a/docs/python-sdk/fastmcp-utilities-inspect.mdx
+++ b/docs/python-sdk/fastmcp-utilities-inspect.mdx
@@ -10,7 +10,7 @@ Utilities for inspecting FastMCP instances.
## Functions
-### `inspect_fastmcp_v2` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `inspect_fastmcp_v2` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo
@@ -26,7 +26,7 @@ Extract information from a FastMCP v2.x instance.
- FastMCPInfo dataclass containing the extracted information
-### `inspect_fastmcp_v1` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `inspect_fastmcp_v1` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L236" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
inspect_fastmcp_v1(mcp: FastMCP1x) -> FastMCPInfo
@@ -42,7 +42,7 @@ Extract information from a FastMCP v1.x instance using a Client.
- FastMCPInfo dataclass containing the extracted information
-### `inspect_fastmcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L390" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `inspect_fastmcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L378" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
inspect_fastmcp(mcp: FastMCP[Any] | FastMCP1x) -> FastMCPInfo
@@ -61,7 +61,7 @@ and uses the appropriate extraction method.
- FastMCPInfo dataclass containing the extracted information
-### `format_fastmcp_info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L415" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `format_fastmcp_info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L403" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
format_fastmcp_info(info: FastMCPInfo) -> bytes
@@ -73,7 +73,7 @@ Format FastMCPInfo as FastMCP-specific JSON.
This includes FastMCP-specific fields like tags, enabled, annotations, etc.
-### `format_mcp_info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L444" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `format_mcp_info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L432" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
format_mcp_info(mcp: FastMCP[Any] | FastMCP1x) -> bytes
@@ -86,7 +86,7 @@ Uses Client to get the standard MCP protocol format with camelCase fields.
Includes version metadata at the top level.
-### `format_info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L477" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `format_info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L465" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
format_info(mcp: FastMCP[Any] | FastMCP1x, format: InspectFormat | Literal['fastmcp', 'mcp'], info: FastMCPInfo | None = None) -> bytes
@@ -112,31 +112,31 @@ Format server information according to the specified format.
Information about a tool.
-### `PromptInfo` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `PromptInfo` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Information about a prompt.
-### `ResourceInfo` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ResourceInfo` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Information about a resource.
-### `TemplateInfo` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `TemplateInfo` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Information about a resource template.
-### `FastMCPInfo` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `FastMCPInfo` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Information extracted from a FastMCP instance.
-### `InspectFormat` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L408" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `InspectFormat` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/inspect.py#L396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Output format for inspect command.
diff --git a/docs/python-sdk/fastmcp-utilities-visibility.mdx b/docs/python-sdk/fastmcp-utilities-visibility.mdx
new file mode 100644
index 000000000..ade14110e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-visibility.mdx
@@ -0,0 +1,86 @@
+---
+title: visibility
+sidebarTitle: visibility
+---
+
+# `fastmcp.utilities.visibility`
+
+
+Visibility filtering for FastMCP components.
+
+This module provides the VisibilityFilter class which handles blocklist and
+allowlist logic for controlling component visibility at both the provider
+and server levels.
+
+
+## Classes
+
+### `VisibilityFilter` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/visibility.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Manages component visibility with blocklist and allowlist support.
+
+Both servers and providers use this class to control which components
+are visible. Visibility is hierarchical: if a component is hidden at
+any level (provider or server), it's hidden to the client.
+
+Filtering logic (blocklist wins over allowlist):
+1. If component key is in _disabled_keys β†’ HIDDEN
+2. If any component tag is in _disabled_tags β†’ HIDDEN
+3. If _default_enabled is False and component not in allowlist β†’ HIDDEN
+4. Otherwise β†’ VISIBLE
+
+The `only=True` flag on enable() switches to allowlist mode:
+- Sets _default_enabled = False
+- Clears existing allowlists
+- Adds specified keys/tags to allowlist
+
+
+**Methods:**
+
+#### `disable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/visibility.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+disable(self) -> None
+```
+
+Add to blocklist (hide components).
+
+**Args:**
+- `keys`: Component keys to hide (e.g., "tool\:my_tool", "resource\:file\://x")
+- `tags`: Tags to hide - any component with these tags will be hidden
+
+
+#### `enable` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/visibility.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+enable(self) -> None
+```
+
+Remove from blocklist, or set allowlist with only=True.
+
+**Args:**
+- `keys`: Component keys to show
+- `tags`: Tags to show
+- `only`: If True, switches to allowlist mode - ONLY show these keys/tags.
+This sets default visibility to False, clears existing allowlists,
+and adds the specified keys/tags to the allowlist.
+
+
+#### `reset` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/visibility.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+reset(self) -> None
+```
+
+Reset to default state (everything enabled, no filters).
+
+
+#### `is_enabled` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/visibility.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+is_enabled(self, component: FastMCPComponent) -> bool
+```
+
+Check if component is enabled. Blocklist wins over allowlist.
+