diff --git a/docs/docs.json b/docs/docs.json
index 54b5ab439..4a499ef2c 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -494,10 +494,10 @@
"group": "transforms",
"pages": [
"python-sdk/fastmcp-server-transforms-__init__",
+ "python-sdk/fastmcp-server-transforms-enabled",
"python-sdk/fastmcp-server-transforms-namespace",
"python-sdk/fastmcp-server-transforms-tool_transform",
- "python-sdk/fastmcp-server-transforms-version_filter",
- "python-sdk/fastmcp-server-transforms-enabled"
+ "python-sdk/fastmcp-server-transforms-version_filter"
]
}
]
@@ -568,6 +568,7 @@
"python-sdk/fastmcp-utilities-openapi-schemas"
]
},
+ "python-sdk/fastmcp-utilities-pagination",
"python-sdk/fastmcp-utilities-tests",
"python-sdk/fastmcp-utilities-types",
"python-sdk/fastmcp-utilities-ui",
diff --git a/docs/python-sdk/fastmcp-client-client.mdx b/docs/python-sdk/fastmcp-client-client.mdx
index 9bdf9108a..3c9315106 100644
--- a/docs/python-sdk/fastmcp-client-client.mdx
+++ b/docs/python-sdk/fastmcp-client-client.mdx
@@ -242,6 +242,9 @@ list_resources_mcp(self) -> mcp.types.ListResourcesResult
Send a resources/list request and return the complete MCP protocol result.
+**Args:**
+- `cursor`: Optional pagination cursor from a previous request's nextCursor.
+
**Returns:**
- mcp.types.ListResourcesResult: The complete response object from the protocol,
containing the list of resources and any additional metadata.
@@ -251,23 +254,27 @@ containing the list of resources and any additional metadata.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_resources`
+#### `list_resources`
```python
list_resources(self) -> list[mcp.types.Resource]
```
-Retrieve a list of resources available on the server.
+Retrieve all resources available on the server.
+
+This method automatically fetches all pages if the server paginates results,
+returning the complete list. For manual pagination control (e.g., to handle
+large result sets incrementally), use list_resources_mcp() with the cursor parameter.
**Returns:**
-- list\[mcp.types.Resource]: A list of Resource objects.
+- list\[mcp.types.Resource]: A list of all Resource objects.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_resource_templates_mcp`
+#### `list_resource_templates_mcp`
```python
list_resource_templates_mcp(self) -> mcp.types.ListResourceTemplatesResult
@@ -275,6 +282,9 @@ list_resource_templates_mcp(self) -> mcp.types.ListResourceTemplatesResult
Send a resources/listResourceTemplates request and return the complete MCP protocol result.
+**Args:**
+- `cursor`: Optional pagination cursor from a previous request's nextCursor.
+
**Returns:**
- mcp.types.ListResourceTemplatesResult: The complete response object from the protocol,
containing the list of resource templates and any additional metadata.
@@ -284,23 +294,28 @@ containing the list of resource templates and any additional metadata.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_resource_templates`
+#### `list_resource_templates`
```python
list_resource_templates(self) -> list[mcp.types.ResourceTemplate]
```
-Retrieve a list of resource templates available on the server.
+Retrieve all resource templates available on the server.
+
+This method automatically fetches all pages if the server paginates results,
+returning the complete list. For manual pagination control (e.g., to handle
+large result sets incrementally), use list_resource_templates_mcp() with the
+cursor parameter.
**Returns:**
-- list\[mcp.types.ResourceTemplate]: A list of ResourceTemplate objects.
+- list\[mcp.types.ResourceTemplate]: A list of all ResourceTemplate objects.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `read_resource_mcp`
+#### `read_resource_mcp`
```python
read_resource_mcp(self, uri: AnyUrl | str, meta: dict[str, Any] | None = None) -> mcp.types.ReadResourceResult
@@ -321,19 +336,19 @@ containing the resource contents and any additional metadata.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `read_resource`
+#### `read_resource`
```python
read_resource(self, uri: AnyUrl | str) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]
```
-#### `read_resource`
+#### `read_resource`
```python
read_resource(self, uri: AnyUrl | str) -> ResourceTask
```
-#### `read_resource`
+#### `read_resource`
```python
read_resource(self, uri: AnyUrl | str) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents] | ResourceTask
@@ -343,6 +358,8 @@ Read the contents of a resource or resolved template.
**Args:**
- `uri`: The URI of the resource to read. Can be a string or an AnyUrl object.
+- `version`: Specific version to read. If None, reads highest version.
+- `meta`: Optional request-level metadata.
- `task`: If True, execute as background task (SEP-1686). Defaults to False.
- `task_id`: Optional client-provided task ID (auto-generated if not provided).
- `ttl`: Time to keep results available in milliseconds (default 60s).
@@ -356,7 +373,7 @@ A list of content objects if task=False, or a ResourceTask object if task=True.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_prompts_mcp`
+#### `list_prompts_mcp`
```python
list_prompts_mcp(self) -> mcp.types.ListPromptsResult
@@ -364,6 +381,9 @@ list_prompts_mcp(self) -> mcp.types.ListPromptsResult
Send a prompts/list request and return the complete MCP protocol result.
+**Args:**
+- `cursor`: Optional pagination cursor from a previous request's nextCursor.
+
**Returns:**
- mcp.types.ListPromptsResult: The complete response object from the protocol,
containing the list of prompts and any additional metadata.
@@ -373,23 +393,27 @@ containing the list of prompts and any additional metadata.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_prompts`
+#### `list_prompts`
```python
list_prompts(self) -> list[mcp.types.Prompt]
```
-Retrieve a list of prompts available on the server.
+Retrieve all prompts available on the server.
+
+This method automatically fetches all pages if the server paginates results,
+returning the complete list. For manual pagination control (e.g., to handle
+large result sets incrementally), use list_prompts_mcp() with the cursor parameter.
**Returns:**
-- list\[mcp.types.Prompt]: A list of Prompt objects.
+- list\[mcp.types.Prompt]: A list of all Prompt objects.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `get_prompt_mcp`
+#### `get_prompt_mcp`
```python
get_prompt_mcp(self, name: str, arguments: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) -> mcp.types.GetPromptResult
@@ -411,19 +435,19 @@ containing the prompt messages and any additional metadata.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `get_prompt`
+#### `get_prompt`
```python
get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.GetPromptResult
```
-#### `get_prompt`
+#### `get_prompt`
```python
get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> PromptTask
```
-#### `get_prompt`
+#### `get_prompt`
```python
get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.GetPromptResult | PromptTask
@@ -434,6 +458,8 @@ Retrieve a rendered prompt message list from the server.
**Args:**
- `name`: The name of the prompt to retrieve.
- `arguments`: Arguments to pass to the prompt. Defaults to None.
+- `version`: Specific prompt version to get. If None, gets highest version.
+- `meta`: Optional request-level metadata.
- `task`: If True, execute as background task (SEP-1686). Defaults to False.
- `task_id`: Optional client-provided task ID (auto-generated if not provided).
- `ttl`: Time to keep results available in milliseconds (default 60s).
@@ -447,7 +473,7 @@ or a PromptTask object if task=True.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `complete_mcp`
+#### `complete_mcp`
```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
@@ -470,7 +496,7 @@ containing the completion and any additional metadata.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `complete`
+#### `complete`
```python
complete(self, ref: mcp.types.ResourceTemplateReference | mcp.types.PromptReference, argument: dict[str, str], context_arguments: dict[str, Any] | None = None) -> mcp.types.Completion
@@ -492,7 +518,7 @@ include with the completion request. Defaults to None.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_tools_mcp`
+#### `list_tools_mcp`
```python
list_tools_mcp(self) -> mcp.types.ListToolsResult
@@ -500,6 +526,9 @@ list_tools_mcp(self) -> mcp.types.ListToolsResult
Send a tools/list request and return the complete MCP protocol result.
+**Args:**
+- `cursor`: Optional pagination cursor from a previous request's nextCursor.
+
**Returns:**
- mcp.types.ListToolsResult: The complete response object from the protocol,
containing the list of tools and any additional metadata.
@@ -509,23 +538,27 @@ containing the list of tools and any additional metadata.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_tools`
+#### `list_tools`
```python
list_tools(self) -> list[mcp.types.Tool]
```
-Retrieve a list of tools available on the server.
+Retrieve all tools available on the server.
+
+This method automatically fetches all pages if the server paginates results,
+returning the complete list. For manual pagination control (e.g., to handle
+large result sets incrementally), use list_tools_mcp() with the cursor parameter.
**Returns:**
-- list\[mcp.types.Tool]: A list of Tool objects.
+- list\[mcp.types.Tool]: A list of all Tool objects.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `call_tool_mcp`
+#### `call_tool_mcp`
```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
@@ -555,19 +588,19 @@ containing the tool result and any additional metadata.
- `McpError`: If the tool call requests results in a TimeoutError | JSONRPCError
-#### `call_tool`
+#### `call_tool`
```python
call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult
```
-#### `call_tool`
+#### `call_tool`
```python
call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> ToolTask
```
-#### `call_tool`
+#### `call_tool`
```python
call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult | ToolTask
@@ -580,6 +613,7 @@ Unlike call_tool_mcp, this method raises a ToolError if the tool call results in
**Args:**
- `name`: The name of the tool to call.
- `arguments`: Arguments to pass to the tool. Defaults to None.
+- `version`: Specific tool version to call. If None, calls highest version.
- `timeout`: The timeout for the tool call. Defaults to None.
- `progress_handler`: The progress handler to use for the tool call. Defaults to None.
- `raise_on_error`: Whether to raise an exception if the tool call results in an error. Defaults to True.
@@ -606,7 +640,7 @@ raw result object.
- `RuntimeError`: If called while the client is not connected.
-#### `get_task_status`
+#### `get_task_status`
```python
get_task_status(self, task_id: str) -> GetTaskResult
@@ -627,7 +661,7 @@ Sends a 'tasks/get' MCP protocol request over the existing transport.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `get_task_result`
+#### `get_task_result`
```python
get_task_result(self, task_id: str) -> Any
@@ -649,7 +683,7 @@ Returns the raw result - callers should parse it appropriately.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `list_tasks`
+#### `list_tasks`
```python
list_tasks(self, cursor: str | None = None, limit: int = 50) -> dict[str, Any]
@@ -675,7 +709,7 @@ querying status for locally tracked task IDs.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `cancel_task`
+#### `cancel_task`
```python
cancel_task(self, task_id: str) -> mcp.types.CancelTaskResult
@@ -697,7 +731,7 @@ and transition to cancelled state.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
-#### `generate_name`
+#### `generate_name`
```python
generate_name(cls, name: str | None = None) -> str
diff --git a/docs/python-sdk/fastmcp-client-transports.mdx b/docs/python-sdk/fastmcp-client-transports.mdx
index bdf965c95..1d84977af 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`
+### `infer_transport`
```python
infer_transport(transport: ClientTransport | FastMCP | FastMCP1Server | AnyUrl | Path | MCPConfig | dict[str, Any] | str) -> ClientTransport
@@ -299,7 +299,7 @@ async with client:
connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
```
-#### `close`
+#### `close`
```python
close(self)
diff --git a/docs/python-sdk/fastmcp-prompts-function_prompt.mdx b/docs/python-sdk/fastmcp-prompts-function_prompt.mdx
index c8e48ef9c..3c543de88 100644
--- a/docs/python-sdk/fastmcp-prompts-function_prompt.mdx
+++ b/docs/python-sdk/fastmcp-prompts-function_prompt.mdx
@@ -10,7 +10,7 @@ Standalone @prompt decorator for FastMCP.
## Functions
-### `prompt`
+### `prompt`
```python
prompt(name_or_fn: str | Callable[..., Any] | None = None) -> Any
@@ -37,7 +37,7 @@ Protocol for functions decorated with @prompt.
Metadata attached to functions by the @prompt decorator.
-### `FunctionPrompt`
+### `FunctionPrompt`
A prompt that is a function.
@@ -45,7 +45,7 @@ A prompt that is a function.
**Methods:**
-#### `from_function`
+#### `from_function`
```python
from_function(cls, fn: Callable[..., Any]) -> FunctionPrompt
@@ -66,7 +66,7 @@ The function can return:
- PromptResult: used directly
-#### `render`
+#### `render`
```python
render(self, arguments: dict[str, Any] | None = None) -> PromptResult
@@ -75,7 +75,7 @@ render(self, arguments: dict[str, Any] | None = None) -> PromptResult
Render the prompt with arguments.
-#### `register_with_docket`
+#### `register_with_docket`
```python
register_with_docket(self, docket: Docket) -> None
@@ -87,7 +87,7 @@ FunctionPrompt registers the underlying function, which has the user's
Depends parameters for docket to resolve.
-#### `add_to_docket`
+#### `add_to_docket`
```python
add_to_docket(self, docket: Docket, arguments: dict[str, Any] | None, **kwargs: Any) -> Execution
diff --git a/docs/python-sdk/fastmcp-resources-function_resource.mdx b/docs/python-sdk/fastmcp-resources-function_resource.mdx
index ad184b53c..e7d710744 100644
--- a/docs/python-sdk/fastmcp-resources-function_resource.mdx
+++ b/docs/python-sdk/fastmcp-resources-function_resource.mdx
@@ -10,7 +10,7 @@ Standalone @resource decorator for FastMCP.
## Functions
-### `resource`
+### `resource`
```python
resource(uri: str) -> Callable[[F], F]
@@ -37,7 +37,7 @@ Protocol for functions decorated with @resource.
Metadata attached to functions by the @resource decorator.
-### `FunctionResource`
+### `FunctionResource`
A resource that defers data loading by wrapping a function.
@@ -54,7 +54,7 @@ The function can return:
**Methods:**
-#### `from_function`
+#### `from_function`
```python
from_function(cls, fn: Callable[..., Any], uri: str | AnyUrl | None = None) -> FunctionResource
@@ -71,7 +71,7 @@ individual parameters must not be passed.
Cannot be used together with metadata parameter.
-#### `read`
+#### `read`
```python
read(self) -> str | bytes | ResourceResult
@@ -80,7 +80,7 @@ read(self) -> str | bytes | ResourceResult
Read the resource by calling the wrapped function.
-#### `register_with_docket`
+#### `register_with_docket`
```python
register_with_docket(self, docket: Docket) -> None
diff --git a/docs/python-sdk/fastmcp-server-context.mdx b/docs/python-sdk/fastmcp-server-context.mdx
index 822efb8c6..2fa8088d5 100644
--- a/docs/python-sdk/fastmcp-server-context.mdx
+++ b/docs/python-sdk/fastmcp-server-context.mdx
@@ -182,7 +182,7 @@ List all available resources from the server.
- List of Resource objects available on the server
-#### `list_prompts`
+#### `list_prompts`
```python
list_prompts(self) -> list[SDKPrompt]
@@ -194,7 +194,7 @@ List all available prompts from the server.
- List of Prompt objects available on the server
-#### `get_prompt`
+#### `get_prompt`
```python
get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> GetPromptResult
@@ -210,7 +210,7 @@ Get a prompt by name with optional arguments.
- The prompt result
-#### `read_resource`
+#### `read_resource`
```python
read_resource(self, uri: str | AnyUrl) -> ResourceResult
@@ -225,7 +225,7 @@ Read a resource by URI.
- ResourceResult with contents
-#### `log`
+#### `log`
```python
log(self, message: str, level: LoggingLevel | None = None, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
@@ -243,7 +243,7 @@ Messages sent to Clients are also logged to the `fastmcp.server.context.to_clien
- `extra`: Optional mapping for additional arguments
-#### `transport`
+#### `transport`
```python
transport(self) -> TransportType | None
@@ -255,7 +255,7 @@ Returns the transport type used to run this server: "stdio", "sse",
or "streamable-http". Returns None if called outside of a server context.
-#### `client_id`
+#### `client_id`
```python
client_id(self) -> str | None
@@ -264,7 +264,7 @@ client_id(self) -> str | None
Get the client ID if available.
-#### `request_id`
+#### `request_id`
```python
request_id(self) -> str
@@ -275,7 +275,7 @@ Get the unique ID for this request.
Raises RuntimeError if MCP request context is not available.
-#### `session_id`
+#### `session_id`
```python
session_id(self) -> str
@@ -292,7 +292,7 @@ the same client session.
- for other transports.
-#### `session`
+#### `session`
```python
session(self) -> ServerSession
@@ -303,7 +303,7 @@ Access to the underlying session for advanced usage.
Raises RuntimeError if MCP request context is not available.
-#### `debug`
+#### `debug`
```python
debug(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
@@ -314,7 +314,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`
+#### `info`
```python
info(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
@@ -325,7 +325,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`
+#### `warning`
```python
warning(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
@@ -336,7 +336,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`
+#### `error`
```python
error(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
@@ -347,7 +347,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`
+#### `list_roots`
```python
list_roots(self) -> list[Root]
@@ -356,7 +356,7 @@ list_roots(self) -> list[Root]
List the roots available to the server, as indicated by the client.
-#### `send_notification`
+#### `send_notification`
```python
send_notification(self, notification: mcp.types.ServerNotificationType) -> None
@@ -372,7 +372,7 @@ for the background flusher.
- `notification`: An MCP notification instance (e.g., ToolListChangedNotification())
-#### `send_notification_sync`
+#### `send_notification_sync`
```python
send_notification_sync(self, notification: mcp.types.ServerNotificationType) -> None
@@ -387,7 +387,7 @@ sent within ~1 second by the background flusher.
- `notification`: An MCP notification instance (e.g., ToolListChangedNotification())
-#### `close_sse_stream`
+#### `close_sse_stream`
```python
close_sse_stream(self) -> None
@@ -405,7 +405,7 @@ Instead of holding a connection open for minutes, you can periodically close
and let the client reconnect.
-#### `sample_step`
+#### `sample_step`
```python
sample_step(self, messages: str | Sequence[str | SamplingMessage]) -> SampleStep
@@ -442,7 +442,7 @@ Tools can raise ToolError to bypass masking.
- - .text: The text content (if any)
-#### `sample`
+#### `sample`
```python
sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[ResultT]
@@ -451,7 +451,7 @@ sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[
Overload: With result_type, returns SamplingResult[ResultT].
-#### `sample`
+#### `sample`
```python
sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[str]
@@ -460,7 +460,7 @@ sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[
Overload: Without result_type, returns SamplingResult[str].
-#### `sample`
+#### `sample`
```python
sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[ResultT] | SamplingResult[str]
@@ -502,43 +502,43 @@ Tools can raise ToolError to bypass masking.
- - .history: All messages exchanged during sampling
-#### `elicit`
+#### `elicit`
```python
elicit(self, message: str, response_type: None) -> AcceptedElicitation[dict[str, Any]] | DeclinedElicitation | CancelledElicitation
```
-#### `elicit`
+#### `elicit`
```python
elicit(self, message: str, response_type: type[T]) -> AcceptedElicitation[T] | DeclinedElicitation | CancelledElicitation
```
-#### `elicit`
+#### `elicit`
```python
elicit(self, message: str, response_type: list[str]) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation
```
-#### `elicit`
+#### `elicit`
```python
elicit(self, message: str, response_type: dict[str, dict[str, str]]) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation
```
-#### `elicit`
+#### `elicit`
```python
elicit(self, message: str, response_type: list[list[str]]) -> AcceptedElicitation[list[str]] | DeclinedElicitation | CancelledElicitation
```
-#### `elicit`
+#### `elicit`
```python
elicit(self, message: str, response_type: list[dict[str, dict[str, str]]]) -> AcceptedElicitation[list[str]] | DeclinedElicitation | CancelledElicitation
```
-#### `elicit`
+#### `elicit`
```python
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
@@ -567,7 +567,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`
+#### `set_state`
```python
set_state(self, key: str, value: Any) -> None
@@ -580,7 +580,7 @@ The key is automatically prefixed with the session identifier.
State expires after 1 day to prevent unbounded memory growth.
-#### `get_state`
+#### `get_state`
```python
get_state(self, key: str) -> Any
@@ -591,7 +591,7 @@ Get a value from the session-scoped state store.
Returns None if the key is not found.
-#### `delete_state`
+#### `delete_state`
```python
delete_state(self, key: str) -> None
diff --git a/docs/python-sdk/fastmcp-server-middleware-authorization.mdx b/docs/python-sdk/fastmcp-server-middleware-authorization.mdx
index f5a41afdc..a7853b5c6 100644
--- a/docs/python-sdk/fastmcp-server-middleware-authorization.mdx
+++ b/docs/python-sdk/fastmcp-server-middleware-authorization.mdx
@@ -70,7 +70,7 @@ on_call_tool(self, context: MiddlewareContext[mt.CallToolRequestParams], call_ne
Check auth before tool execution.
-#### `on_list_resources`
+#### `on_list_resources`
```python
on_list_resources(self, context: MiddlewareContext[mt.ListResourcesRequest], call_next: CallNext[mt.ListResourcesRequest, Sequence[Resource]]) -> Sequence[Resource]
@@ -79,7 +79,7 @@ on_list_resources(self, context: MiddlewareContext[mt.ListResourcesRequest], cal
Filter resources/list response based on auth checks.
-#### `on_read_resource`
+#### `on_read_resource`
```python
on_read_resource(self, context: MiddlewareContext[mt.ReadResourceRequestParams], call_next: CallNext[mt.ReadResourceRequestParams, ResourceResult]) -> ResourceResult
@@ -88,7 +88,7 @@ on_read_resource(self, context: MiddlewareContext[mt.ReadResourceRequestParams],
Check auth before resource read.
-#### `on_list_resource_templates`
+#### `on_list_resource_templates`
```python
on_list_resource_templates(self, context: MiddlewareContext[mt.ListResourceTemplatesRequest], call_next: CallNext[mt.ListResourceTemplatesRequest, Sequence[ResourceTemplate]]) -> Sequence[ResourceTemplate]
@@ -97,7 +97,7 @@ on_list_resource_templates(self, context: MiddlewareContext[mt.ListResourceTempl
Filter resource templates/list response based on auth checks.
-#### `on_list_prompts`
+#### `on_list_prompts`
```python
on_list_prompts(self, context: MiddlewareContext[mt.ListPromptsRequest], call_next: CallNext[mt.ListPromptsRequest, Sequence[Prompt]]) -> Sequence[Prompt]
@@ -106,7 +106,7 @@ on_list_prompts(self, context: MiddlewareContext[mt.ListPromptsRequest], call_ne
Filter prompts/list response based on auth checks.
-#### `on_get_prompt`
+#### `on_get_prompt`
```python
on_get_prompt(self, context: MiddlewareContext[mt.GetPromptRequestParams], call_next: CallNext[mt.GetPromptRequestParams, PromptResult]) -> PromptResult
diff --git a/docs/python-sdk/fastmcp-server-providers-__init__.mdx b/docs/python-sdk/fastmcp-server-providers-__init__.mdx
index 277e67e60..b7addb653 100644
--- a/docs/python-sdk/fastmcp-server-providers-__init__.mdx
+++ b/docs/python-sdk/fastmcp-server-providers-__init__.mdx
@@ -21,11 +21,11 @@ Example:
def __init__(self, db_url: str):
self.db = Database(db_url)
- async def list_tools(self) -> list[Tool]:
+ 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:
+ 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
diff --git a/docs/python-sdk/fastmcp-server-providers-aggregate.mdx b/docs/python-sdk/fastmcp-server-providers-aggregate.mdx
index 61b90c87f..d128d1a5d 100644
--- a/docs/python-sdk/fastmcp-server-providers-aggregate.mdx
+++ b/docs/python-sdk/fastmcp-server-providers-aggregate.mdx
@@ -8,119 +8,41 @@ sidebarTitle: aggregate
AggregateProvider for combining multiple providers into one.
-This module provides `AggregateProvider` which presents multiple providers
-as a single unified provider. Used internally by FastMCP for aggregating
-components from all providers.
+This module provides `AggregateProvider`, a utility class that presents
+multiple providers as a single unified provider. Useful when you want to
+combine custom providers without creating a full FastMCP server.
+
+Example:
+ ```python
+ from fastmcp.server.providers import AggregateProvider
+
+ # Combine multiple providers into one
+ combined = AggregateProvider([provider1, provider2, provider3])
+
+ # Use like any other provider
+ tools = await combined.list_tools()
+ ```
## Classes
-### `AggregateProvider`
+### `AggregateProvider`
-Presents multiple providers as a single provider.
+Utility provider that combines multiple providers into one.
Components are aggregated from all providers. For get_* operations,
providers are queried in parallel and the highest version is returned.
Errors from individual providers are logged and skipped (graceful degradation).
+This is useful when you want to combine custom providers without creating
+a full FastMCP server.
+
**Methods:**
-#### `list_tools`
-
-```python
-list_tools(self) -> Sequence[Tool]
-```
-
-List all tools from all providers (with transforms applied).
-
-
-#### `get_tool`
-
-```python
-get_tool(self, name: str, version: VersionSpec | None = None) -> Tool | None
-```
-
-Get tool by name.
-
-**Args:**
-- `name`: The tool name.
-- `version`: If None, returns highest version across all providers.
-If specified, returns highest version matching the spec from any provider.
-
-
-#### `list_resources`
-
-```python
-list_resources(self) -> Sequence[Resource]
-```
-
-List all resources from all providers (with transforms applied).
-
-
-#### `get_resource`
-
-```python
-get_resource(self, uri: str, version: VersionSpec | None = None) -> Resource | None
-```
-
-Get resource by URI.
-
-**Args:**
-- `uri`: The resource URI.
-- `version`: If None, returns highest version across all providers.
-If specified, returns highest version matching the spec from any provider.
-
-
-#### `list_resource_templates`
-
-```python
-list_resource_templates(self) -> Sequence[ResourceTemplate]
-```
-
-List all resource templates from all providers (with transforms applied).
-
-
-#### `get_resource_template`
-
-```python
-get_resource_template(self, uri: str, version: VersionSpec | None = None) -> ResourceTemplate | None
-```
-
-Get resource template by URI.
-
-**Args:**
-- `uri`: The template URI to match.
-- `version`: If None, returns highest version across all providers.
-If specified, returns highest version matching the spec from any provider.
-
-
-#### `list_prompts`
-
-```python
-list_prompts(self) -> Sequence[Prompt]
-```
-
-List all prompts from all providers (with transforms applied).
-
-
-#### `get_prompt`
-
-```python
-get_prompt(self, name: str, version: VersionSpec | None = None) -> Prompt | None
-```
-
-Get prompt by name.
-
-**Args:**
-- `name`: The prompt name.
-- `version`: If None, returns highest version across all providers.
-If specified, returns highest version matching the spec from any provider.
-
-
-#### `get_tasks`
+#### `get_tasks`
```python
get_tasks(self) -> Sequence[FastMCPComponent]
@@ -129,7 +51,7 @@ get_tasks(self) -> Sequence[FastMCPComponent]
Get all task-eligible components from all providers.
-#### `lifespan`
+#### `lifespan`
```python
lifespan(self) -> AsyncIterator[None]
diff --git a/docs/python-sdk/fastmcp-server-providers-base.mdx b/docs/python-sdk/fastmcp-server-providers-base.mdx
index 623c24e21..36ed3cc06 100644
--- a/docs/python-sdk/fastmcp-server-providers-base.mdx
+++ b/docs/python-sdk/fastmcp-server-providers-base.mdx
@@ -22,11 +22,11 @@ Example:
super().__init__()
self.db = Database(db_url)
- async def list_tools(self) -> list[Tool]:
+ 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:
+ 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
@@ -36,7 +36,7 @@ Example:
## Classes
-### `Provider`
+### `Provider`
Base class for dynamic component providers.
@@ -48,7 +48,16 @@ supports.
**Methods:**
-#### `add_transform`
+#### `transforms`
+
+```python
+transforms(self) -> list[Transform]
+```
+
+All transforms applied to components from this provider.
+
+
+#### `add_transform`
```python
add_transform(self, transform: Transform) -> None
@@ -63,132 +72,134 @@ through the provider. They're applied in order - first added is innermost.
- `transform`: The transform to add.
-#### `list_tools`
+#### `list_tools`
```python
list_tools(self) -> Sequence[Tool]
```
-Return all available tools.
+List tools with all transforms applied.
-Override to provide tools dynamically. Returns ALL versions of all tools.
-The server handles deduplication to show one tool per name.
+Builds a middleware chain: base → transforms (in order).
+Each transform wraps the previous via call_next.
+Components may be marked as disabled but are NOT filtered here -
+filtering happens at the server level to allow session transforms to override.
+
+**Returns:**
+- Transformed sequence of tools (including disabled ones).
-#### `get_tool`
+#### `get_tool`
```python
get_tool(self, name: str, version: VersionSpec | None = None) -> Tool | None
```
-Get a specific tool by name.
+Get tool by transformed name with all transforms applied.
-Default implementation filters list_tools() and picks the highest version
-that matches the spec.
+Note: This method does NOT filter disabled components. The Server
+(FastMCP) performs enabled filtering after all transforms complete,
+allowing session-level transforms to override provider-level disables.
**Args:**
-- `name`: The tool name.
+- `name`: The transformed tool name to look up.
- `version`: Optional version filter. If None, returns highest version.
- If specified, returns highest version matching the spec.
**Returns:**
-- The Tool if found, or None to continue searching other providers.
+- The tool if found (may be marked disabled), None if not found.
-#### `list_resources`
+#### `list_resources`
```python
list_resources(self) -> Sequence[Resource]
```
-Return all available resources.
+List resources with all transforms applied.
-Override to provide resources dynamically. Returns ALL versions of all resources.
-The server handles deduplication to show one resource per URI.
+Components may be marked as disabled but are NOT filtered here.
-#### `get_resource`
+#### `get_resource`
```python
get_resource(self, uri: str, version: VersionSpec | None = None) -> Resource | None
```
-Get a specific resource by URI.
+Get resource by transformed URI with all transforms applied.
-Default implementation filters list_resources() and returns highest
-version matching the spec.
+Note: This method does NOT filter disabled components. The Server
+(FastMCP) performs enabled filtering after all transforms complete.
**Args:**
-- `uri`: The resource URI.
+- `uri`: The transformed resource URI to look up.
- `version`: Optional version filter. If None, returns highest version.
**Returns:**
-- The Resource if found, or None to continue searching other providers.
+- The resource if found (may be marked disabled), None if not found.
-#### `list_resource_templates`
+#### `list_resource_templates`
```python
list_resource_templates(self) -> Sequence[ResourceTemplate]
```
-Return all available resource templates.
+List resource templates with all transforms applied.
-Override to provide resource templates dynamically. Returns ALL versions.
-The server handles deduplication.
+Components may be marked as disabled but are NOT filtered here.
-#### `get_resource_template`
+#### `get_resource_template`
```python
get_resource_template(self, uri: str, version: VersionSpec | None = None) -> ResourceTemplate | None
```
-Get a resource template that matches the given URI.
+Get resource template by transformed URI with all transforms applied.
-Default implementation lists all templates, finds those whose pattern
-matches the URI, and returns the highest version matching the spec.
+Note: This method does NOT filter disabled components. The Server
+(FastMCP) performs enabled filtering after all transforms complete.
**Args:**
-- `uri`: The URI to match against templates.
+- `uri`: The transformed template URI to look up.
- `version`: Optional version filter. If None, returns highest version.
**Returns:**
-- The ResourceTemplate if a matching one is found, or None to continue searching.
+- The template if found (may be marked disabled), None if not found.
-#### `list_prompts`
+#### `list_prompts`
```python
list_prompts(self) -> Sequence[Prompt]
```
-Return all available prompts.
+List prompts with all transforms applied.
-Override to provide prompts dynamically. Returns ALL versions of all prompts.
-The server handles deduplication to show one prompt per name.
+Components may be marked as disabled but are NOT filtered here.
-#### `get_prompt`
+#### `get_prompt`
```python
get_prompt(self, name: str, version: VersionSpec | None = None) -> Prompt | None
```
-Get a specific prompt by name.
+Get prompt by transformed name with all transforms applied.
-Default implementation filters list_prompts() and picks the highest version
-matching the spec.
+Note: This method does NOT filter disabled components. The Server
+(FastMCP) performs enabled filtering after all transforms complete.
**Args:**
-- `name`: The prompt name.
+- `name`: The transformed prompt name to look up.
- `version`: Optional version filter. If None, returns highest version.
**Returns:**
-- The Prompt if found, or None to continue searching other providers.
+- The prompt if found (may be marked disabled), None if not found.
-#### `get_tasks`
+#### `get_tasks`
```python
get_tasks(self) -> Sequence[FastMCPComponent]
@@ -203,7 +214,7 @@ for components with task_config.mode != 'forbidden'.
Used by the server during startup to register functions with Docket.
-#### `lifespan`
+#### `lifespan`
```python
lifespan(self) -> AsyncIterator[None]
@@ -219,29 +230,54 @@ The lifespan scope matches the server's lifespan - code before yield
runs at startup, code after yield runs at shutdown.
-#### `enable`
+#### `enable`
```python
-enable(self) -> None
+enable(self) -> Self
```
-Enable components by removing from blocklist, or set allowlist with only=True.
+Enable components matching all specified criteria.
+
+Adds an enabled transform that marks matching components as enabled.
+Later transforms override earlier ones, so enable after disable makes
+the component enabled.
+
+With only=True, switches to allowlist mode - first disables everything,
+then enables matching components.
**Args:**
-- `keys`: Keys to enable (e.g., "tool\:my_tool@" for unversioned, "tool\:my_tool@1.0" for versioned).
-- `tags`: Tags to enable - components with these tags will be enabled.
-- `only`: If True, switches to allowlist mode - ONLY show these keys/tags.
+- `names`: Component names or URIs to enable.
+- `keys`: Component keys to enable (e.g., {"tool\:my_tool@v1"}).
+- `version`: Component version spec to enable (e.g., VersionSpec(eq="v1") or
+VersionSpec(gte="v2")). Unversioned components will not match.
+- `tags`: Enable components with these tags.
+- `components`: Component types to include (e.g., ["tool", "prompt"]).
+- `only`: If True, ONLY enable matching components (allowlist mode).
+
+**Returns:**
+- Self for method chaining.
-#### `disable`
+#### `disable`
```python
-disable(self) -> None
+disable(self) -> Self
```
-Disable components by adding to the blocklist.
+Disable components matching all specified criteria.
+
+Adds an enabled transform that marks matching components as disabled.
+Components can be re-enabled by calling enable() with matching criteria
+(the later transform wins).
**Args:**
-- `keys`: Keys to disable (e.g., "tool\:my_tool@" for unversioned, "tool\:my_tool@1.0" for versioned).
-- `tags`: Tags to disable - components with these tags will be disabled.
+- `names`: Component names or URIs to disable.
+- `keys`: Component keys to disable (e.g., {"tool\:my_tool@v1"}).
+- `version`: Component version spec to disable (e.g., VersionSpec(eq="v1") or
+VersionSpec(gte="v2")). Unversioned components will not match.
+- `tags`: Disable components with these tags.
+- `components`: Component types to include (e.g., ["tool", "prompt"]).
+
+**Returns:**
+- Self for method chaining.
diff --git a/docs/python-sdk/fastmcp-server-providers-fastmcp_provider.mdx b/docs/python-sdk/fastmcp-server-providers-fastmcp_provider.mdx
index b12db1ca1..fda42ad19 100644
--- a/docs/python-sdk/fastmcp-server-providers-fastmcp_provider.mdx
+++ b/docs/python-sdk/fastmcp-server-providers-fastmcp_provider.mdx
@@ -18,7 +18,7 @@ executed.
## Classes
-### `FastMCPProviderTool`
+### `FastMCPProviderTool`
Tool that delegates execution to a wrapped server's middleware.
@@ -30,7 +30,7 @@ chain is executed.
**Methods:**
-#### `wrap`
+#### `wrap`
```python
wrap(cls, server: Any, tool: Tool) -> FastMCPProviderTool
@@ -39,7 +39,7 @@ wrap(cls, server: Any, tool: Tool) -> FastMCPProviderTool
Wrap a Tool to delegate execution to the server's middleware.
-#### `run`
+#### `run`
```python
run(self, arguments: dict[str, Any]) -> ToolResult
@@ -51,13 +51,13 @@ This is called when the tool is used within a TransformedTool
forwarding function or other contexts where task_meta is not available.
-#### `get_span_attributes`
+#### `get_span_attributes`
```python
get_span_attributes(self) -> dict[str, Any]
```
-### `FastMCPProviderResource`
+### `FastMCPProviderResource`
Resource that delegates reading to a wrapped server's read_resource().
@@ -68,7 +68,7 @@ When `read()` is called, this resource invokes the wrapped server's
**Methods:**
-#### `wrap`
+#### `wrap`
```python
wrap(cls, server: Any, resource: Resource) -> FastMCPProviderResource
@@ -77,13 +77,13 @@ wrap(cls, server: Any, resource: Resource) -> FastMCPProviderResource
Wrap a Resource to delegate reading to the server's middleware.
-#### `get_span_attributes`
+#### `get_span_attributes`
```python
get_span_attributes(self) -> dict[str, Any]
```
-### `FastMCPProviderPrompt`
+### `FastMCPProviderPrompt`
Prompt that delegates rendering to a wrapped server's render_prompt().
@@ -94,7 +94,7 @@ When `render()` is called, this prompt invokes the wrapped server's
**Methods:**
-#### `wrap`
+#### `wrap`
```python
wrap(cls, server: Any, prompt: Prompt) -> FastMCPProviderPrompt
@@ -103,7 +103,7 @@ wrap(cls, server: Any, prompt: Prompt) -> FastMCPProviderPrompt
Wrap a Prompt to delegate rendering to the server's middleware.
-#### `render`
+#### `render`
```python
render(self, arguments: dict[str, Any] | None = None) -> PromptResult
@@ -115,13 +115,13 @@ This is called when the prompt is used within a transformed context
or other contexts where task_meta is not available.
-#### `get_span_attributes`
+#### `get_span_attributes`
```python
get_span_attributes(self) -> dict[str, Any]
```
-### `FastMCPProviderResourceTemplate`
+### `FastMCPProviderResourceTemplate`
Resource template that creates FastMCPProviderResources.
@@ -133,7 +133,7 @@ when read.
**Methods:**
-#### `wrap`
+#### `wrap`
```python
wrap(cls, server: Any, template: ResourceTemplate) -> FastMCPProviderResourceTemplate
@@ -142,7 +142,7 @@ wrap(cls, server: Any, template: ResourceTemplate) -> FastMCPProviderResourceTem
Wrap a ResourceTemplate to create FastMCPProviderResources.
-#### `create_resource`
+#### `create_resource`
```python
create_resource(self, uri: str, params: dict[str, Any]) -> Resource
@@ -155,7 +155,7 @@ We use `_original_uri_template` with `params` to construct the internal
URI that the nested server understands.
-#### `read`
+#### `read`
```python
read(self, arguments: dict[str, Any]) -> str | bytes | ResourceResult
@@ -167,7 +167,7 @@ Reads the resource via the wrapped server and returns the ResourceResult.
This method is called by Docket during background task execution.
-#### `register_with_docket`
+#### `register_with_docket`
```python
register_with_docket(self, docket: Docket) -> None
@@ -176,7 +176,7 @@ register_with_docket(self, docket: Docket) -> None
No-op: the child's actual template is registered via get_tasks().
-#### `add_to_docket`
+#### `add_to_docket`
```python
add_to_docket(self, docket: Docket, params: dict[str, Any], **kwargs: Any) -> Execution
@@ -188,13 +188,13 @@ The child's FunctionResourceTemplate.fn is registered (via get_tasks),
and it expects splatted **kwargs, so we splat params here.
-#### `get_span_attributes`
+#### `get_span_attributes`
```python
get_span_attributes(self) -> dict[str, Any]
```
-### `FastMCPProvider`
+### `FastMCPProvider`
Provider that wraps a FastMCP server.
@@ -210,105 +210,7 @@ This ensures middleware runs when components are executed.
**Methods:**
-#### `list_tools`
-
-```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`
-
-```python
-get_tool(self, name: str, version: VersionSpec | None = None) -> Tool | None
-```
-
-Get a tool by name as a FastMCPProviderTool.
-
-Passes the full VersionSpec to the nested server, which handles both
-exact version matching and range filtering.
-
-
-#### `list_resources`
-
-```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`
-
-```python
-get_resource(self, uri: str, version: VersionSpec | None = None) -> Resource | None
-```
-
-Get a concrete resource by URI as a FastMCPProviderResource.
-
-Passes the full VersionSpec to the nested server, which handles both
-exact version matching and range filtering.
-
-
-#### `list_resource_templates`
-
-```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`
-
-```python
-get_resource_template(self, uri: str, version: VersionSpec | None = None) -> ResourceTemplate | None
-```
-
-Get a resource template that matches the given URI.
-
-Passes the full VersionSpec to the nested server, which handles both
-exact version matching and range filtering.
-
-
-#### `list_prompts`
-
-```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`
-
-```python
-get_prompt(self, name: str, version: VersionSpec | None = None) -> Prompt | None
-```
-
-Get a prompt by name as a FastMCPProviderPrompt.
-
-Passes the full VersionSpec to the nested server, which handles both
-exact version matching and range filtering.
-
-
-#### `get_tasks`
+#### `get_tasks`
```python
get_tasks(self) -> Sequence[FastMCPComponent]
@@ -317,12 +219,12 @@ 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. Uses _source_get_tasks() to get
-components with child server's transforms applied, then applies this
-provider's transforms for correct registration keys.
+functions get registered with Docket. Gets components with child
+server's transforms applied, then applies this provider's transforms
+for correct registration keys.
-#### `lifespan`
+#### `lifespan`
```python
lifespan(self) -> AsyncIterator[None]
diff --git a/docs/python-sdk/fastmcp-server-providers-filesystem.mdx b/docs/python-sdk/fastmcp-server-providers-filesystem.mdx
index 55e9b342c..9684ce94c 100644
--- a/docs/python-sdk/fastmcp-server-providers-filesystem.mdx
+++ b/docs/python-sdk/fastmcp-server-providers-filesystem.mdx
@@ -52,77 +52,3 @@ the standalone decorators:
- `reload`: If True, re-scan files on every request (dev mode).
Defaults to False (scan once at init, cache results).
-
-**Methods:**
-
-#### `list_tools`
-
-```python
-list_tools(self) -> Sequence[Tool]
-```
-
-Return all tools, reloading if in reload mode.
-
-
-#### `get_tool`
-
-```python
-get_tool(self, name: str, version: VersionSpec | None = None) -> Tool | None
-```
-
-Get a tool by name, reloading if in reload mode.
-
-
-#### `list_resources`
-
-```python
-list_resources(self) -> Sequence[Resource]
-```
-
-Return all resources, reloading if in reload mode.
-
-
-#### `get_resource`
-
-```python
-get_resource(self, uri: str, version: VersionSpec | None = None) -> Resource | None
-```
-
-Get a resource by URI, reloading if in reload mode.
-
-
-#### `list_resource_templates`
-
-```python
-list_resource_templates(self) -> Sequence[ResourceTemplate]
-```
-
-Return all resource templates, reloading if in reload mode.
-
-
-#### `get_resource_template`
-
-```python
-get_resource_template(self, uri: str, version: VersionSpec | None = None) -> ResourceTemplate | None
-```
-
-Get a resource template, reloading if in reload mode.
-
-
-#### `list_prompts`
-
-```python
-list_prompts(self) -> Sequence[Prompt]
-```
-
-Return all prompts, reloading if in reload mode.
-
-
-#### `get_prompt`
-
-```python
-get_prompt(self, name: str, version: VersionSpec | None = None) -> Prompt | None
-```
-
-Get a prompt by name, reloading if in reload mode.
-
diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider.mdx
index 247d9e1ba..0cd3fbbb9 100644
--- a/docs/python-sdk/fastmcp-server-providers-local_provider.mdx
+++ b/docs/python-sdk/fastmcp-server-providers-local_provider.mdx
@@ -58,7 +58,7 @@ Add a tool to this provider's storage.
Accepts either a Tool object or a decorated function with __fastmcp__ metadata.
-#### `remove_tool`
+#### `remove_tool`
```python
remove_tool(self, name: str, version: str | None = None) -> None
@@ -74,7 +74,7 @@ Remove tool(s) from this provider's storage.
- `KeyError`: If no matching tool is found.
-#### `add_resource`
+#### `add_resource`
```python
add_resource(self, resource: Resource | ResourceTemplate | Callable[..., Any]) -> Resource | ResourceTemplate
@@ -85,7 +85,7 @@ Add a resource to this provider's storage.
Accepts either a Resource/ResourceTemplate object or a decorated function with __fastmcp__ metadata.
-#### `remove_resource`
+#### `remove_resource`
```python
remove_resource(self, uri: str, version: str | None = None) -> None
@@ -101,7 +101,7 @@ Remove resource(s) from this provider's storage.
- `KeyError`: If no matching resource is found.
-#### `add_template`
+#### `add_template`
```python
add_template(self, template: ResourceTemplate) -> ResourceTemplate
@@ -110,7 +110,7 @@ add_template(self, template: ResourceTemplate) -> ResourceTemplate
Add a resource template to this provider's storage.
-#### `remove_template`
+#### `remove_template`
```python
remove_template(self, uri_template: str, version: str | None = None) -> None
@@ -126,7 +126,7 @@ Remove resource template(s) from this provider's storage.
- `KeyError`: If no matching template is found.
-#### `add_prompt`
+#### `add_prompt`
```python
add_prompt(self, prompt: Prompt | Callable[..., Any]) -> Prompt
@@ -137,7 +137,7 @@ Add a prompt to this provider's storage.
Accepts either a Prompt object or a decorated function with __fastmcp__ metadata.
-#### `remove_prompt`
+#### `remove_prompt`
```python
remove_prompt(self, name: str, version: str | None = None) -> None
@@ -153,95 +153,7 @@ Remove prompt(s) from this provider's storage.
- `KeyError`: If no matching prompt is found.
-#### `list_tools`
-
-```python
-list_tools(self) -> Sequence[Tool]
-```
-
-Return all visible tools.
-
-
-#### `get_tool`
-
-```python
-get_tool(self, name: str, version: VersionSpec | None = None) -> Tool | None
-```
-
-Get a tool by name.
-
-**Args:**
-- `name`: The tool name.
-- `version`: Optional version filter. If None, returns highest version.
-
-
-#### `list_resources`
-
-```python
-list_resources(self) -> Sequence[Resource]
-```
-
-Return all visible resources.
-
-
-#### `get_resource`
-
-```python
-get_resource(self, uri: str, version: VersionSpec | None = None) -> Resource | None
-```
-
-Get a resource by URI.
-
-**Args:**
-- `uri`: The resource URI.
-- `version`: Optional version filter. If None, returns highest version.
-
-
-#### `list_resource_templates`
-
-```python
-list_resource_templates(self) -> Sequence[ResourceTemplate]
-```
-
-Return all visible resource templates.
-
-
-#### `get_resource_template`
-
-```python
-get_resource_template(self, uri: str, version: VersionSpec | None = None) -> ResourceTemplate | None
-```
-
-Get a resource template that matches the given URI.
-
-**Args:**
-- `uri`: The URI to match against templates.
-- `version`: Optional version filter. If None, returns highest version.
-
-
-#### `list_prompts`
-
-```python
-list_prompts(self) -> Sequence[Prompt]
-```
-
-Return all visible prompts.
-
-
-#### `get_prompt`
-
-```python
-get_prompt(self, name: str, version: VersionSpec | None = None) -> Prompt | None
-```
-
-Get a prompt by name.
-
-**Args:**
-- `name`: The prompt name.
-- `version`: Optional version filter. If None, returns highest version.
-
-
-#### `get_tasks`
+#### `get_tasks`
```python
get_tasks(self) -> Sequence[FastMCPComponent]
@@ -254,19 +166,19 @@ This includes both FunctionTool/Resource/Prompt instances created via
decorators and custom Tool/Resource/Prompt subclasses.
-#### `tool`
+#### `tool`
```python
tool(self, name_or_fn: AnyFunction) -> FunctionTool
```
-#### `tool`
+#### `tool`
```python
tool(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionTool]
```
-#### `tool`
+#### `tool`
```python
tool(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionTool] | FunctionTool | partial[Callable[[AnyFunction], FunctionTool] | FunctionTool]
@@ -300,7 +212,7 @@ This decorator supports multiple calling patterns:
- The registered FunctionTool or a decorator function.
-#### `resource`
+#### `resource`
```python
resource(self, uri: str) -> Callable[[AnyFunction], Resource | ResourceTemplate | AnyFunction]
@@ -329,19 +241,19 @@ has parameters, it will be registered as a template resource.
- A decorator function.
-#### `prompt`
+#### `prompt`
```python
prompt(self, name_or_fn: AnyFunction) -> FunctionPrompt
```
-#### `prompt`
+#### `prompt`
```python
prompt(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionPrompt]
```
-#### `prompt`
+#### `prompt`
```python
prompt(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt | partial[Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt]
diff --git a/docs/python-sdk/fastmcp-server-providers-openapi-provider.mdx b/docs/python-sdk/fastmcp-server-providers-openapi-provider.mdx
index 2e262c525..87768733d 100644
--- a/docs/python-sdk/fastmcp-server-providers-openapi-provider.mdx
+++ b/docs/python-sdk/fastmcp-server-providers-openapi-provider.mdx
@@ -21,69 +21,6 @@ spec. Each component makes HTTP calls to the described API endpoints.
**Methods:**
-#### `list_tools`
-
-```python
-list_tools(self) -> Sequence[Tool]
-```
-
-Return all tools created from the OpenAPI spec.
-
-
-#### `get_tool`
-
-```python
-get_tool(self, name: str, version: VersionSpec | None = None) -> Tool | None
-```
-
-Get a tool by name.
-
-
-#### `list_resources`
-
-```python
-list_resources(self) -> Sequence[Resource]
-```
-
-Return all resources created from the OpenAPI spec.
-
-
-#### `get_resource`
-
-```python
-get_resource(self, uri: str, version: VersionSpec | None = None) -> Resource | None
-```
-
-Get a resource by URI.
-
-
-#### `list_resource_templates`
-
-```python
-list_resource_templates(self) -> Sequence[ResourceTemplate]
-```
-
-Return all resource templates created from the OpenAPI spec.
-
-
-#### `get_resource_template`
-
-```python
-get_resource_template(self, uri: str, version: VersionSpec | None = None) -> ResourceTemplate | None
-```
-
-Get a resource template that matches the given URI.
-
-
-#### `list_prompts`
-
-```python
-list_prompts(self) -> Sequence[Prompt]
-```
-
-Return empty list - OpenAPI doesn't create prompts.
-
-
#### `get_tasks`
```python
diff --git a/docs/python-sdk/fastmcp-server-providers-proxy.mdx b/docs/python-sdk/fastmcp-server-providers-proxy.mdx
index 55aca8243..803adb973 100644
--- a/docs/python-sdk/fastmcp-server-providers-proxy.mdx
+++ b/docs/python-sdk/fastmcp-server-providers-proxy.mdx
@@ -245,42 +245,6 @@ because tasks cannot be executed through a proxy.
**Methods:**
-#### `list_tools`
-
-```python
-list_tools(self) -> Sequence[Tool]
-```
-
-List all tools from the remote server.
-
-
-#### `list_resources`
-
-```python
-list_resources(self) -> Sequence[Resource]
-```
-
-List all resources from the remote server.
-
-
-#### `list_resource_templates`
-
-```python
-list_resource_templates(self) -> Sequence[ResourceTemplate]
-```
-
-List all resource templates from the remote server.
-
-
-#### `list_prompts`
-
-```python
-list_prompts(self) -> Sequence[Prompt]
-```
-
-List all prompts from the remote server.
-
-
#### `get_tasks`
```python
diff --git a/docs/python-sdk/fastmcp-server-server.mdx b/docs/python-sdk/fastmcp-server-server.mdx
index b627ea0bb..ae6831070 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`
+### `default_lifespan`
```python
default_lifespan(server: FastMCP[LifespanResultT]) -> AsyncIterator[Any]
@@ -26,7 +26,7 @@ Default lifespan context manager that does nothing.
- An empty dictionary as the lifespan result.
-### `create_proxy`
+### `create_proxy`
```python
create_proxy(target: Client[ClientTransportT] | ClientTransport | FastMCP[Any] | FastMCP1Server | AnyUrl | Path | MCPConfig | dict[str, Any] | str, **settings: Any) -> FastMCPProxy
@@ -54,59 +54,59 @@ use `FastMCPProxy` or `ProxyProvider` directly from `fastmcp.server.providers.pr
## Classes
-### `StateValue`
+### `StateValue`
Wrapper for stored context state values.
-### `FastMCP`
+### `FastMCP`
**Methods:**
-#### `settings`
+#### `settings`
```python
settings(self) -> Settings
```
-#### `name`
+#### `name`
```python
name(self) -> str
```
-#### `instructions`
+#### `instructions`
```python
instructions(self) -> str | None
```
-#### `instructions`
+#### `instructions`
```python
instructions(self, value: str | None) -> None
```
-#### `version`
+#### `version`
```python
version(self) -> str | None
```
-#### `website_url`
+#### `website_url`
```python
website_url(self) -> str | None
```
-#### `icons`
+#### `icons`
```python
icons(self) -> list[mcp.types.Icon]
```
-#### `docket`
+#### `docket`
```python
docket(self) -> Docket | None
@@ -117,7 +117,7 @@ Get the Docket instance if Docket support is enabled.
Returns None if Docket is not enabled or server hasn't been started yet.
-#### `run_async`
+#### `run_async`
```python
run_async(self, transport: Transport | None = None, show_banner: bool | None = None, **transport_kwargs: Any) -> None
@@ -131,7 +131,7 @@ Run the FastMCP server asynchronously.
FASTMCP_SHOW_SERVER_BANNER setting (default\: True).
-#### `run`
+#### `run`
```python
run(self, transport: Transport | None = None, show_banner: bool | None = None, **transport_kwargs: Any) -> None
@@ -145,13 +145,13 @@ Run the FastMCP server. Note this is a synchronous function.
FASTMCP_SHOW_SERVER_BANNER setting (default\: True).
-#### `add_middleware`
+#### `add_middleware`
```python
add_middleware(self, middleware: Middleware) -> None
```
-#### `add_provider`
+#### `add_provider`
```python
add_provider(self, provider: Provider) -> None
@@ -167,7 +167,19 @@ always take precedence over providers.
- `provider`: A Provider instance that will provide components dynamically.
-#### `add_transform`
+#### `get_tasks`
+
+```python
+get_tasks(self) -> Sequence[FastMCPComponent]
+```
+
+Get task-eligible components with all transforms applied.
+
+Overrides Provider.get_tasks() to collect task-eligible components
+from all sub-providers and apply server-level transforms.
+
+
+#### `add_transform`
```python
add_transform(self, transform: Transform) -> None
@@ -182,7 +194,7 @@ They transform tools, resources, and prompts from ALL providers.
- `transform`: The transform to add.
-#### `add_tool_transformation`
+#### `add_tool_transformation`
```python
add_tool_transformation(self, tool_name: str, transformation: ToolTransformConfig) -> None
@@ -194,7 +206,7 @@ Add a tool transformation.
Use ``add_transform(ToolTransform({...}))`` instead.
-#### `remove_tool_transformation`
+#### `remove_tool_transformation`
```python
remove_tool_transformation(self, _tool_name: str) -> None
@@ -203,38 +215,10 @@ remove_tool_transformation(self, _tool_name: str) -> None
Remove a tool transformation.
.. deprecated::
- Tool transformations are now immutable. Use visibility controls instead.
+ Tool transformations are now immutable. Use enable/disable controls instead.
-#### `enable`
-
-```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@"`` for unversioned, ``"tool\:my_tool@1.0"`` for versioned).
-- `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.
-
-
-#### `disable`
-
-```python
-disable(self) -> None
-```
-
-Disable components by adding to the blocklist.
-
-**Args:**
-- `keys`: Keys to disable (e.g., ``"tool\:my_tool@"`` for unversioned, ``"tool\:my_tool@1.0"`` for versioned).
-- `tags`: Tags to disable - components with these tags will be disabled.
-
-
-#### `get_tools`
+#### `get_tools`
```python
get_tools(self) -> list[Tool]
@@ -243,33 +227,34 @@ get_tools(self) -> list[Tool]
Get all enabled tools from providers.
Queries all providers via the root provider (which applies provider transforms,
-server transforms, and visibility filtering). First provider wins for duplicate keys.
+server transforms, and enabled filtering). First provider wins for duplicate keys.
**Args:**
-- `run_middleware`: If True, apply the middleware chain before
-returning results. Used by MCP handlers and mounted servers.
+- `run_middleware`: If True, apply the middleware chain before returning.
+Used by MCP handlers and FastMCPProvider for nested servers.
-#### `get_tool`
+#### `get_tool`
```python
-get_tool(self, name: str, version: VersionSpec | str | None = None) -> Tool
+get_tool(self, name: str, version: VersionSpec | None = None) -> Tool | None
```
-Get an enabled tool by name.
+Get a tool by name, filtering disabled tools.
-Queries providers with full transform chain (provider transforms + server transforms + visibility).
-Returns only if enabled and authorized.
+Overrides Provider.get_tool() to add enabled filtering after all
+transforms (including session-level) have been applied. This ensures
+session transforms can override provider-level disables.
**Args:**
- `name`: The tool name.
-- `version`: Version filter. Can be\:
-- None\: returns highest version
-- str\: returns exact version match
-- VersionSpec\: returns best match within spec (highest matching)
+- `version`: Version filter (None returns highest version).
+
+**Returns:**
+- The tool if found and enabled, None otherwise.
-#### `get_resources`
+#### `get_resources`
```python
get_resources(self) -> list[Resource]
@@ -278,33 +263,33 @@ get_resources(self) -> list[Resource]
Get all enabled resources from providers.
Queries all providers via the root provider (which applies provider transforms,
-server transforms, and visibility filtering). First provider wins for duplicate keys.
+server transforms, and enabled filtering). First provider wins for duplicate keys.
**Args:**
-- `run_middleware`: If True, apply the middleware chain before
-returning results. Used by MCP handlers and mounted servers.
+- `run_middleware`: If True, apply the middleware chain before returning.
+Used by MCP handlers and FastMCPProvider for nested servers.
-#### `get_resource`
+#### `get_resource`
```python
-get_resource(self, uri: str, version: VersionSpec | str | None = None) -> Resource
+get_resource(self, uri: str, version: VersionSpec | None = None) -> Resource | None
```
-Get an enabled resource by URI.
+Get a resource by URI, filtering disabled resources.
-Queries providers with full transform chain (provider transforms + server transforms + visibility).
-Returns only if enabled and authorized.
+Overrides Provider.get_resource() to add enabled filtering after all
+transforms (including session-level) have been applied.
**Args:**
- `uri`: The resource URI.
-- `version`: Version filter. Can be\:
-- None\: returns highest version
-- str\: returns exact version match
-- VersionSpec\: returns best match within spec (highest matching)
+- `version`: Version filter (None returns highest version).
+
+**Returns:**
+- The resource if found and enabled, None otherwise.
-#### `get_resource_templates`
+#### `get_resource_templates`
```python
get_resource_templates(self) -> list[ResourceTemplate]
@@ -313,33 +298,33 @@ get_resource_templates(self) -> list[ResourceTemplate]
Get all enabled resource templates from providers.
Queries all providers via the root provider (which applies provider transforms,
-server transforms, and visibility filtering). First provider wins for duplicate keys.
+server transforms, and enabled filtering). First provider wins for duplicate keys.
**Args:**
-- `run_middleware`: If True, apply the middleware chain before
-returning results. Used by MCP handlers and mounted servers.
+- `run_middleware`: If True, apply the middleware chain before returning.
+Used by MCP handlers and FastMCPProvider for nested servers.
-#### `get_resource_template`
+#### `get_resource_template`
```python
-get_resource_template(self, uri: str, version: VersionSpec | str | None = None) -> ResourceTemplate
+get_resource_template(self, uri: str, version: VersionSpec | None = None) -> ResourceTemplate | None
```
-Get an enabled resource template that matches the given URI.
+Get a resource template by URI, filtering disabled templates.
-Queries providers with full transform chain (provider transforms + server transforms + visibility).
-Returns only if enabled and authorized.
+Overrides Provider.get_resource_template() to add enabled filtering after
+all transforms (including session-level) have been applied.
**Args:**
-- `uri`: The template URI to match.
-- `version`: Version filter. Can be\:
-- None\: returns highest version
-- str\: returns exact version match
-- VersionSpec\: returns best match within spec (highest matching)
+- `uri`: The template URI.
+- `version`: Version filter (None returns highest version).
+
+**Returns:**
+- The template if found and enabled, None otherwise.
-#### `get_prompts`
+#### `get_prompts`
```python
get_prompts(self) -> list[Prompt]
@@ -348,45 +333,45 @@ get_prompts(self) -> list[Prompt]
Get all enabled prompts from providers.
Queries all providers via the root provider (which applies provider transforms,
-server transforms, and visibility filtering). First provider wins for duplicate keys.
+server transforms, and enabled filtering). First provider wins for duplicate keys.
**Args:**
-- `run_middleware`: If True, apply the middleware chain before
-returning results. Used by MCP handlers and mounted servers.
+- `run_middleware`: If True, apply the middleware chain before returning.
+Used by MCP handlers and FastMCPProvider for nested servers.
-#### `get_prompt`
+#### `get_prompt`
```python
-get_prompt(self, name: str, version: VersionSpec | str | None = None) -> Prompt
+get_prompt(self, name: str, version: VersionSpec | None = None) -> Prompt | None
```
-Get an enabled prompt by name.
+Get a prompt by name, filtering disabled prompts.
-Queries providers with full transform chain (provider transforms + server transforms + visibility).
-Returns only if enabled and authorized.
+Overrides Provider.get_prompt() to add enabled filtering after all
+transforms (including session-level) have been applied.
**Args:**
- `name`: The prompt name.
-- `version`: Version filter. Can be\:
-- None\: returns highest version
-- str\: returns exact version match
-- VersionSpec\: returns best match within spec (highest matching)
+- `version`: Version filter (None returns highest version).
+
+**Returns:**
+- The prompt if found and enabled, None otherwise.
-#### `call_tool`
+#### `call_tool`
```python
call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> ToolResult
```
-#### `call_tool`
+#### `call_tool`
```python
call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.CreateTaskResult
```
-#### `call_tool`
+#### `call_tool`
```python
call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> ToolResult | mcp.types.CreateTaskResult
@@ -399,6 +384,7 @@ This is the public API for executing tools. By default, middleware is applied.
**Args:**
- `name`: The tool name
- `arguments`: Tool arguments (optional)
+- `version`: Specific version to call. If None, calls highest version.
- `run_middleware`: If True (default), apply the middleware chain.
Set to False when called from middleware to avoid re-applying.
- `task_meta`: If provided, execute as a background task and return
@@ -415,19 +401,19 @@ return ToolResult.
- `ValidationError`: If arguments fail validation
-#### `read_resource`
+#### `read_resource`
```python
read_resource(self, uri: str) -> ResourceResult
```
-#### `read_resource`
+#### `read_resource`
```python
read_resource(self, uri: str) -> mcp.types.CreateTaskResult
```
-#### `read_resource`
+#### `read_resource`
```python
read_resource(self, uri: str) -> ResourceResult | mcp.types.CreateTaskResult
@@ -440,6 +426,7 @@ Checks concrete resources first, then templates.
**Args:**
- `uri`: The resource URI
+- `version`: Specific version to read. If None, reads highest version.
- `run_middleware`: If True (default), apply the middleware chain.
Set to False when called from middleware to avoid re-applying.
- `task_meta`: If provided, execute as a background task and return
@@ -455,19 +442,19 @@ return ResourceResult.
- `ResourceError`: If resource read fails
-#### `render_prompt`
+#### `render_prompt`
```python
render_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> PromptResult
```
-#### `render_prompt`
+#### `render_prompt`
```python
render_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.CreateTaskResult
```
-#### `render_prompt`
+#### `render_prompt`
```python
render_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> PromptResult | mcp.types.CreateTaskResult
@@ -481,6 +468,7 @@ Use get_prompt() to retrieve the prompt definition without rendering.
**Args:**
- `name`: The prompt name
- `arguments`: Prompt arguments (optional)
+- `version`: Specific version to render. If None, renders highest version.
- `run_middleware`: If True (default), apply the middleware chain.
Set to False when called from middleware to avoid re-applying.
- `task_meta`: If provided, execute as a background task and return
@@ -496,7 +484,7 @@ return PromptResult.
- `PromptError`: If prompt rendering fails
-#### `custom_route`
+#### `custom_route`
```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]]]
@@ -517,7 +505,7 @@ Starlette's reverse URL lookup feature)
- `include_in_schema`: Whether to include in OpenAPI schema, defaults to True
-#### `add_tool`
+#### `add_tool`
```python
add_tool(self, tool: Tool | Callable[..., Any]) -> Tool
@@ -535,7 +523,7 @@ with the Context type annotation. See the @tool decorator for examples.
- The tool instance that was added to the server.
-#### `remove_tool`
+#### `remove_tool`
```python
remove_tool(self, name: str, version: str | None = None) -> None
@@ -551,19 +539,19 @@ Remove tool(s) from the server.
- `NotFoundError`: If no matching tool is found.
-#### `tool`
+#### `tool`
```python
tool(self, name_or_fn: AnyFunction) -> FunctionTool
```
-#### `tool`
+#### `tool`
```python
tool(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionTool]
```
-#### `tool`
+#### `tool`
```python
tool(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionTool] | FunctionTool | partial[Callable[[AnyFunction], FunctionTool] | FunctionTool]
@@ -619,7 +607,7 @@ server.tool(my_function, name="custom_name")
```
-#### `add_resource`
+#### `add_resource`
```python
add_resource(self, resource: Resource | Callable[..., Any]) -> Resource | ResourceTemplate
@@ -634,7 +622,7 @@ Add a resource to the server.
- The resource instance that was added to the server.
-#### `add_template`
+#### `add_template`
```python
add_template(self, template: ResourceTemplate) -> ResourceTemplate
@@ -649,7 +637,7 @@ Add a resource template to the server.
- The template instance that was added to the server.
-#### `resource`
+#### `resource`
```python
resource(self, uri: str) -> Callable[[AnyFunction], Resource | ResourceTemplate | AnyFunction]
@@ -708,7 +696,7 @@ async def get_weather(city: str) -> str:
```
-#### `add_prompt`
+#### `add_prompt`
```python
add_prompt(self, prompt: Prompt | Callable[..., Any]) -> Prompt
@@ -723,19 +711,19 @@ Add a prompt to the server.
- The prompt instance that was added to the server.
-#### `prompt`
+#### `prompt`
```python
prompt(self, name_or_fn: AnyFunction) -> FunctionPrompt
```
-#### `prompt`
+#### `prompt`
```python
prompt(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionPrompt]
```
-#### `prompt`
+#### `prompt`
```python
prompt(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt | partial[Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt]
@@ -812,7 +800,7 @@ Decorator to register a prompt.
```
-#### `run_stdio_async`
+#### `run_stdio_async`
```python
run_stdio_async(self, show_banner: bool = True, log_level: str | None = None, stateless: bool = False) -> None
@@ -826,7 +814,7 @@ Run the server using stdio transport.
- `stateless`: Whether to run in stateless mode (no session initialization)
-#### `run_http_async`
+#### `run_http_async`
```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, stateless: bool | None = None) -> None
@@ -847,7 +835,7 @@ Run the server using HTTP transport.
- `stateless`: Alias for stateless_http for CLI consistency
-#### `http_app`
+#### `http_app`
```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
@@ -873,7 +861,7 @@ streamable-http transport.
- A Starlette application configured with the specified transport
-#### `mount`
+#### `mount`
```python
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
@@ -920,7 +908,7 @@ mounted server.
- `prefix`: Deprecated. Use namespace instead.
-#### `import_server`
+#### `import_server`
```python
import_server(self, server: FastMCP[LifespanResultT], prefix: str | None = None) -> None
@@ -961,7 +949,7 @@ templates, and prompts are imported with their original names.
objects are imported with their original names.
-#### `from_openapi`
+#### `from_openapi`
```python
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
@@ -985,7 +973,7 @@ Create a FastMCP server from an OpenAPI specification.
- A FastMCP server with an OpenAPIProvider attached.
-#### `from_fastapi`
+#### `from_fastapi`
```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, timeout: float | None = None, **settings: Any) -> Self
@@ -1009,7 +997,7 @@ Create a FastMCP server from a FastAPI application.
- A FastMCP server with an OpenAPIProvider attached.
-#### `as_proxy`
+#### `as_proxy`
```python
as_proxy(cls, backend: Client[ClientTransportT] | ClientTransport | FastMCP[Any] | FastMCP1Server | AnyUrl | Path | MCPConfig | dict[str, Any] | str, **settings: Any) -> FastMCPProxy
@@ -1027,7 +1015,7 @@ instance or any value accepted as the `transport` argument of
`fastmcp.client.Client` constructor.
-#### `generate_name`
+#### `generate_name`
```python
generate_name(cls, name: str | None = None) -> str
diff --git a/docs/python-sdk/fastmcp-server-tasks-requests.mdx b/docs/python-sdk/fastmcp-server-tasks-requests.mdx
index 50f77596a..01734f1db 100644
--- a/docs/python-sdk/fastmcp-server-tasks-requests.mdx
+++ b/docs/python-sdk/fastmcp-server-tasks-requests.mdx
@@ -16,7 +16,7 @@ This module requires fastmcp[tasks] (pydocket). It is only imported when docket
## Functions
-### `tasks_get_handler`
+### `tasks_get_handler`
```python
tasks_get_handler(server: FastMCP, params: dict[str, Any]) -> GetTaskResult
@@ -33,7 +33,7 @@ Handle MCP 'tasks/get' request (SEP-1686).
- Task status response with spec-compliant fields
-### `tasks_result_handler`
+### `tasks_result_handler`
```python
tasks_result_handler(server: FastMCP, params: dict[str, Any]) -> Any
@@ -52,7 +52,7 @@ Converts raw task return values to MCP types based on task type.
- MCP result (CallToolResult, GetPromptResult, or ReadResourceResult)
-### `tasks_list_handler`
+### `tasks_list_handler`
```python
tasks_list_handler(server: FastMCP, params: dict[str, Any]) -> ListTasksResult
@@ -71,7 +71,7 @@ Note: With client-side tracking, this returns minimal info.
- Response with tasks list and pagination
-### `tasks_cancel_handler`
+### `tasks_cancel_handler`
```python
tasks_cancel_handler(server: FastMCP, params: dict[str, Any]) -> CancelTaskResult
diff --git a/docs/python-sdk/fastmcp-server-transforms-enabled.mdx b/docs/python-sdk/fastmcp-server-transforms-enabled.mdx
index 149e777e2..27e26fd44 100644
--- a/docs/python-sdk/fastmcp-server-transforms-enabled.mdx
+++ b/docs/python-sdk/fastmcp-server-transforms-enabled.mdx
@@ -8,143 +8,20 @@ sidebarTitle: enabled
Enabled transform for marking component enabled state.
-This module provides the `Enabled` class which marks components with enabled/disabled
-state using metadata. Multiple Enabled transforms can be stacked - later transforms
-override earlier ones. Final filtering happens at the Provider level.
-
-
-## Classes
-
-### `Enabled`
-
-
-Sets enabled state on matching components.
-
-Does NOT filter inline - just marks components with enabled state.
-Later transforms in the chain can override earlier marks.
-Final filtering happens at the Provider level after all transforms run.
-
-Filtering logic (blocklist wins over allowlist):
-1. If component key is in _disabled_keys -> DISABLED
-2. If any component tag is in _disabled_tags -> DISABLED
-3. If _default_enabled is False and component not in allowlist -> DISABLED
-4. Otherwise -> ENABLED
-
-Example usage:
-```python
-from fastmcp.server.transforms import Enabled
-
-# Disable components tagged "internal"
-Enabled(False, tags=frozenset({"internal"}))
-
-# Re-enable specific tool (override earlier disable)
-Enabled(True, names={"safe_tool"})
-
-# Allowlist via composition:
-Enabled(False, match_all=True) # disable everything
-Enabled(True, tags=frozenset({"public"})) # enable public
-```
-
-
-**Methods:**
-
-#### `__init__`
-
-```python
-__init__(self, enabled: bool, *, name: str | None = None, version: str | None = None, tags: frozenset[str] | None = None, components: frozenset[str] | None = None, match_all: bool = False) -> None
-```
-
-Initialize an enabled marker.
-
-**Args:**
-- `enabled`: If True, mark matching as enabled; if False, mark as disabled.
-- `name`: Component name to match.
-- `version`: Component version to match.
-- `tags`: Tags to match (component must have at least one).
-- `components`: Component types to match (e.g., frozenset({"tool", "prompt"})).
-- `match_all`: If True, matches all components regardless of other criteria.
-
-
-#### `list_tools`
-
-```python
-list_tools(self, call_next: ListToolsNext) -> Sequence[Tool]
-```
-
-Mark tools by enabled state.
-
-
-#### `get_tool`
-
-```python
-get_tool(self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None) -> Tool | None
-```
-
-Mark tool if found.
-
-
-#### `list_resources`
-
-```python
-list_resources(self, call_next: ListResourcesNext) -> Sequence[Resource]
-```
-
-Mark resources by enabled state.
-
-
-#### `get_resource`
-
-```python
-get_resource(self, uri: str, call_next: GetResourceNext, *, version: VersionSpec | None = None) -> Resource | None
-```
-
-Mark resource if found.
-
-
-#### `list_resource_templates`
-
-```python
-list_resource_templates(self, call_next: ListResourceTemplatesNext) -> Sequence[ResourceTemplate]
-```
-
-Mark resource templates by enabled state.
-
-
-#### `get_resource_template`
-
-```python
-get_resource_template(self, uri: str, call_next: GetResourceTemplateNext, *, version: VersionSpec | None = None) -> ResourceTemplate | None
-```
-
-Mark resource template if found.
-
-
-#### `list_prompts`
-
-```python
-list_prompts(self, call_next: ListPromptsNext) -> Sequence[Prompt]
-```
-
-Mark prompts by enabled state.
-
-
-#### `get_prompt`
-
-```python
-get_prompt(self, name: str, call_next: GetPromptNext, *, version: VersionSpec | None = None) -> Prompt | None
-```
-
-Mark prompt if found.
+Each Enabled instance marks components via internal metadata. Multiple
+enabled transforms can be stacked - later transforms override earlier ones.
+Final filtering happens at the Provider level.
## Functions
-### `is_enabled`
+### `is_enabled`
```python
is_enabled(component: FastMCPComponent) -> bool
```
+
Check if component is enabled.
Returns True if:
@@ -157,4 +34,91 @@ Returns False if enabled mark is False.
- `component`: Component to check.
**Returns:**
-True if component should be enabled/visible to clients.
+- True if component should be enabled/visible to clients.
+
+
+## Classes
+
+### `Enabled`
+
+
+Sets enabled state on matching components.
+
+Does NOT filter inline - just marks components with enabled state.
+Later transforms in the chain can override earlier marks.
+Final filtering happens at the Provider level after all transforms run.
+
+
+**Methods:**
+
+#### `list_tools`
+
+```python
+list_tools(self, call_next: ListToolsNext) -> Sequence[Tool]
+```
+
+Mark tools by enabled state.
+
+
+#### `get_tool`
+
+```python
+get_tool(self, name: str, call_next: GetToolNext) -> Tool | None
+```
+
+Mark tool if found.
+
+
+#### `list_resources`
+
+```python
+list_resources(self, call_next: ListResourcesNext) -> Sequence[Resource]
+```
+
+Mark resources by enabled state.
+
+
+#### `get_resource`
+
+```python
+get_resource(self, uri: str, call_next: GetResourceNext) -> Resource | None
+```
+
+Mark resource if found.
+
+
+#### `list_resource_templates`
+
+```python
+list_resource_templates(self, call_next: ListResourceTemplatesNext) -> Sequence[ResourceTemplate]
+```
+
+Mark resource templates by enabled state.
+
+
+#### `get_resource_template`
+
+```python
+get_resource_template(self, uri: str, call_next: GetResourceTemplateNext) -> ResourceTemplate | None
+```
+
+Mark resource template if found.
+
+
+#### `list_prompts`
+
+```python
+list_prompts(self, call_next: ListPromptsNext) -> Sequence[Prompt]
+```
+
+Mark prompts by enabled state.
+
+
+#### `get_prompt`
+
+```python
+get_prompt(self, name: str, call_next: GetPromptNext) -> Prompt | None
+```
+
+Mark prompt if found.
+
diff --git a/docs/python-sdk/fastmcp-tools-function_tool.mdx b/docs/python-sdk/fastmcp-tools-function_tool.mdx
index b9bd0e7da..0e4b35333 100644
--- a/docs/python-sdk/fastmcp-tools-function_tool.mdx
+++ b/docs/python-sdk/fastmcp-tools-function_tool.mdx
@@ -10,7 +10,7 @@ Standalone @tool decorator for FastMCP.
## Functions
-### `tool`
+### `tool`
```python
tool(name_or_fn: str | Callable[..., Any] | None = None) -> Any
@@ -37,11 +37,11 @@ Protocol for functions decorated with @tool.
Metadata attached to functions by the @tool decorator.
-### `FunctionTool`
+### `FunctionTool`
**Methods:**
-#### `to_mcp_tool`
+#### `to_mcp_tool`
```python
to_mcp_tool(self, **overrides: Any) -> mcp.types.Tool
@@ -52,7 +52,7 @@ Convert the FastMCP tool to an MCP tool.
Extends the base implementation to add task execution mode if enabled.
-#### `from_function`
+#### `from_function`
```python
from_function(cls, fn: Callable[..., Any]) -> FunctionTool
@@ -68,7 +68,7 @@ individual parameters must not be passed.
Cannot be used together with metadata parameter.
-#### `run`
+#### `run`
```python
run(self, arguments: dict[str, Any]) -> ToolResult
@@ -77,7 +77,7 @@ run(self, arguments: dict[str, Any]) -> ToolResult
Run the tool with arguments.
-#### `register_with_docket`
+#### `register_with_docket`
```python
register_with_docket(self, docket: Docket) -> None
@@ -89,7 +89,7 @@ FunctionTool registers the underlying function, which has the user's
Depends parameters for docket to resolve.
-#### `add_to_docket`
+#### `add_to_docket`
```python
add_to_docket(self, docket: Docket, arguments: dict[str, Any], **kwargs: Any) -> Execution
diff --git a/docs/python-sdk/fastmcp-utilities-components.mdx b/docs/python-sdk/fastmcp-utilities-components.mdx
index c93093df2..0acaa7daa 100644
--- a/docs/python-sdk/fastmcp-utilities-components.mdx
+++ b/docs/python-sdk/fastmcp-utilities-components.mdx
@@ -7,7 +7,7 @@ sidebarTitle: components
## Functions
-### `get_fastmcp_metadata`
+### `get_fastmcp_metadata`
```python
get_fastmcp_metadata(meta: dict[str, Any] | None) -> FastMCPMeta
@@ -24,7 +24,7 @@ namespace for compatibility with older FastMCP servers.
### `FastMCPMeta`
-### `FastMCPComponent`
+### `FastMCPComponent`
Base class for FastMCP tools, prompts, resources, and resource templates.
@@ -32,7 +32,7 @@ Base class for FastMCP tools, prompts, resources, and resource templates.
**Methods:**
-#### `make_key`
+#### `make_key`
```python
make_key(cls, identifier: str) -> str
@@ -47,7 +47,7 @@ Construct the lookup key for this component type.
- A prefixed key like "tool:name" or "resource:uri"
-#### `key`
+#### `key`
```python
key(self) -> str
@@ -65,7 +65,7 @@ Subclasses should override this to use their specific identifier.
Base implementation uses name.
-#### `get_meta`
+#### `get_meta`
```python
get_meta(self) -> dict[str, Any]
@@ -77,8 +77,10 @@ Returns a dict that always includes a `fastmcp` key containing:
- `tags`: sorted list of component tags
- `version`: component version (only if set)
+Internal keys (prefixed with `_`) are stripped from the fastmcp namespace.
-#### `enable`
+
+#### `enable`
```python
enable(self) -> None
@@ -87,7 +89,7 @@ enable(self) -> None
Removed in 3.0. Use server.enable(keys=[...]) instead.
-#### `disable`
+#### `disable`
```python
disable(self) -> None
@@ -96,7 +98,7 @@ disable(self) -> None
Removed in 3.0. Use server.disable(keys=[...]) instead.
-#### `copy`
+#### `copy`
```python
copy(self) -> Self
@@ -105,7 +107,7 @@ copy(self) -> Self
Create a copy of the component.
-#### `register_with_docket`
+#### `register_with_docket`
```python
register_with_docket(self, docket: Docket) -> None
@@ -117,7 +119,7 @@ No-ops if task_config.mode is "forbidden". Subclasses override to
register their callable (self.run, self.read, self.render, or self.fn).
-#### `add_to_docket`
+#### `add_to_docket`
```python
add_to_docket(self, docket: Docket, *args: Any, **kwargs: Any) -> Execution
@@ -134,7 +136,7 @@ Subclasses override this to handle their specific calling conventions:
The **kwargs are passed through to docket.add() (e.g., key=task_key).
-#### `get_span_attributes`
+#### `get_span_attributes`
```python
get_span_attributes(self) -> dict[str, Any]
diff --git a/docs/python-sdk/fastmcp-utilities-pagination.mdx b/docs/python-sdk/fastmcp-utilities-pagination.mdx
new file mode 100644
index 000000000..cbea98f40
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-pagination.mdx
@@ -0,0 +1,66 @@
+---
+title: pagination
+sidebarTitle: pagination
+---
+
+# `fastmcp.utilities.pagination`
+
+
+Pagination utilities for MCP list operations.
+
+## Functions
+
+### `paginate_sequence`
+
+```python
+paginate_sequence(items: Sequence[T], cursor: str | None, page_size: int) -> tuple[list[T], str | None]
+```
+
+
+Paginate a sequence of items.
+
+**Args:**
+- `items`: The full sequence to paginate.
+- `cursor`: Optional cursor from a previous request. None for first page.
+- `page_size`: Maximum number of items per page.
+
+**Returns:**
+- Tuple of (page_items, next_cursor). next_cursor is None if no more pages.
+
+**Raises:**
+- `ValueError`: If the cursor is invalid.
+
+
+## Classes
+
+### `CursorState`
+
+
+Internal representation of pagination cursor state.
+
+The cursor encodes the offset into the result set. This is opaque to clients
+per the MCP spec - they should not parse or modify cursors.
+
+
+**Methods:**
+
+#### `encode`
+
+```python
+encode(self) -> str
+```
+
+Encode cursor state to an opaque string.
+
+
+#### `decode`
+
+```python
+decode(cls, cursor: str) -> CursorState
+```
+
+Decode cursor from an opaque string.
+
+**Raises:**
+- `ValueError`: If the cursor is invalid or malformed.
+
diff --git a/docs/python-sdk/fastmcp-utilities-versions.mdx b/docs/python-sdk/fastmcp-utilities-versions.mdx
index 9adb00b50..638220432 100644
--- a/docs/python-sdk/fastmcp-utilities-versions.mdx
+++ b/docs/python-sdk/fastmcp-utilities-versions.mdx
@@ -22,7 +22,7 @@ Examples:
## Functions
-### `parse_version_key`
+### `parse_version_key`
```python
parse_version_key(version: str | None) -> VersionKey
@@ -38,7 +38,7 @@ Parse a version string into a sortable key.
- A VersionKey suitable for sorting.
-### `version_sort_key`
+### `version_sort_key`
```python
version_sort_key(component: FastMCPComponent) -> VersionKey
@@ -56,7 +56,7 @@ Use with sorted() or max() to order components by version.
- A sortable VersionKey.
-### `compare_versions`
+### `compare_versions`
```python
compare_versions(a: str | None, b: str | None) -> int
@@ -73,7 +73,7 @@ Compare two version strings.
- -1 if a < b, 0 if a == b, 1 if a > b.
-### `is_version_greater`
+### `is_version_greater`
```python
is_version_greater(a: str | None, b: str | None) -> bool
@@ -90,7 +90,7 @@ Check if version a is greater than version b.
- True if a > b, False otherwise.
-### `max_version`
+### `max_version`
```python
max_version(a: str | None, b: str | None) -> str | None
@@ -107,7 +107,7 @@ Return the greater of two versions.
- The greater version, or None if both are None.
-### `min_version`
+### `min_version`
```python
min_version(a: str | None, b: str | None) -> str | None
@@ -153,12 +153,16 @@ Check if a version matches this spec.
**Args:**
- `version`: The version to check, or None for unversioned.
+- `match_none`: Whether unversioned (None) components match. Defaults to True
+for backward compatibility with retrieval operations. Set to False
+when filtering (e.g., enable/disable) to exclude unversioned components
+from version-specific rules.
**Returns:**
- True if the version matches the spec.
-#### `intersect`
+#### `intersect`
```python
intersect(self, other: VersionSpec | None) -> VersionSpec
@@ -177,7 +181,7 @@ the intersection validates "1.0" is in range and returns the exact spec.
- A VersionSpec that matches only versions satisfying both specs.
-### `VersionKey`
+### `VersionKey`
A comparable version key that handles None, PEP 440 versions, and strings.