chore: Update SDK documentation (#4155)

2026-08-21 13:04:18 +02:00 · 2026-05-23 08:54:28 -04:00 · 2026-05-23 08:54:28 -04:00 · 6acacf2191
commit 6acacf2191
parent 292e9af087
15 changed files with 804 additions and 30 deletions
--- a/docs/python-sdk/fastmcp-apps-init.mdx
+++ b/docs/python-sdk/fastmcp-apps-init.mdx
@ -1,6 +1,6 @@
 ---
-title: apps
-sidebarTitle: apps
+title: __init__
+sidebarTitle: __init__
 ---

 # `fastmcp.apps`
--- a/docs/python-sdk/fastmcp-apps-app.mdx
+++ b/docs/python-sdk/fastmcp-apps-app.mdx
@ -0,0 +1,146 @@
+---
+title: app
+sidebarTitle: app
+---
+
+# `fastmcp.apps.app`
+
+
+FastMCPApp — a Provider that represents a composable MCP application.
+
+FastMCPApp binds entry-point tools (model calls these) together with backend
+tools (the UI calls these via CallTool).  Backend tools are tagged with
+``meta["fastmcp"]["app"]`` so they can be found through the provider chain
+even when transforms (namespace, visibility, etc.) have renamed or hidden
+them — the server sets a context var that tells ``Provider.get_tool`` to
+fall back to a direct lookup for app-visible tools.
+
+Usage::
+
+    from fastmcp import FastMCP, FastMCPApp
+
+    app = FastMCPApp("Dashboard")
+
+    @app.ui()
+    def show_dashboard() -> Component:
+        return Column(...)
+
+    @app.tool()
+    def save_contact(name: str, email: str) -> str:
+        return name
+
+    server = FastMCP("Platform")
+    server.add_provider(app)
+
+
+## Classes
+
+### `FastMCPApp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Provider that represents an MCP application.
+
+Binds together entry-point tools (``@app.ui``), backend tools
+(``@app.tool``), and the Prefab renderer resource.  Backend tools
+are tagged with ``meta["fastmcp"]["app"]`` so ``Provider.get_tool``
+can find them by original name even when transforms have been applied.
+
+
+**Methods:**
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self, name_or_fn: F) -> F
+```
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self, name_or_fn: str | None = None) -> Callable[[F], F]
+```
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self, name_or_fn: str | AnyFunction | None = None) -> Any
+```
+
+Register a backend tool that the UI calls via CallTool.
+
+Backend tools default to ``visibility=["app"]``.  Pass ``model=True``
+to also expose the tool to the model (``visibility=["app", "model"]``).
+
+Supports multiple calling patterns::
+
+    @app.tool
+    def save(name: str): ...
+
+    @app.tool()
+    def save(name: str): ...
+
+    @app.tool("custom_name")
+    def save(name: str): ...
+
+
+#### `ui` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+ui(self, name_or_fn: F) -> F
+```
+
+#### `ui` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L273" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+ui(self, name_or_fn: str | None = None) -> Callable[[F], F]
+```
+
+#### `ui` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+ui(self, name_or_fn: str | AnyFunction | None = None) -> Any
+```
+
+Register a UI entry-point tool that the model calls.
+
+Entry-point tools default to ``visibility=["model"]`` and auto-wire
+the Prefab renderer resource and CSP. They are tagged with the app
+name so structured content includes ``_meta.fastmcp.app``.
+
+Supports multiple calling patterns::
+
+    @app.ui
+    def dashboard() -> Component: ...
+
+    @app.ui()
+    def dashboard() -> Component: ...
+
+    @app.ui("my_dashboard")
+    def dashboard() -> Component: ...
+
+
+#### `add_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L362" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_tool(self, tool: Tool | Callable[..., Any]) -> Tool
+```
+
+Add a tool to this app programmatically.
+
+The tool is tagged with this app's name for routing.
+
+
+#### `lifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L418" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+lifespan(self) -> AsyncIterator[None]
+```
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L426" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(self, transport: Literal['stdio', 'http', 'sse', 'streamable-http'] | None = None, **kwargs: Any) -> None
+```
+
+Create a temporary FastMCP server and run this app standalone.
+
--- a/docs/python-sdk/fastmcp-apps-approval.mdx
+++ b/docs/python-sdk/fastmcp-apps-approval.mdx
@ -0,0 +1,58 @@
+---
+title: approval
+sidebarTitle: approval
+---
+
+# `fastmcp.apps.approval`
+
+
+Approval — a Provider that adds human-in-the-loop approval to any server.
+
+The LLM presents a summary of what it's about to do, and the user
+approves or rejects via buttons. The result is sent back into the
+conversation as a message, prompting the LLM's next turn.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.approval import Approval
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(Approval())
+
+
+## Classes
+
+### `Approval` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/approval.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Provider that adds human-in-the-loop approval to a server.
+
+The LLM calls the ``request_approval`` tool with a summary and
+optional details. The user sees an approval card with Approve and
+Reject buttons. Clicking either sends a message back into the
+conversation (via ``SendMessage``), triggering the LLM's next turn.
+
+The message appears as if the user sent it, so the LLM sees
+something like ``'"Deploy v3.2 to production" is APPROVED'``.
+
+Example::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.approval import Approval
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(Approval())
+
+Customized::
+
+    Approval(
+        title="Deploy Gate",
+        approve_text="Ship it",
+        approve_variant="default",
+        reject_text="Abort",
+        reject_variant="destructive",
+    )
+
--- a/docs/python-sdk/fastmcp-apps-choice.mdx
+++ b/docs/python-sdk/fastmcp-apps-choice.mdx
@ -0,0 +1,44 @@
+---
+title: choice
+sidebarTitle: choice
+---
+
+# `fastmcp.apps.choice`
+
+
+Choice — a Provider that lets the user pick from a set of options.
+
+The LLM presents options, the user clicks one, and the selection
+flows back into the conversation as a message.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.choice import Choice
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(Choice())
+
+
+## Classes
+
+### `Choice` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/choice.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Provider that lets the user choose from a set of options.
+
+The LLM calls ``choose`` with a prompt and a list of options.
+The user sees a card with one button per option. Clicking a button
+sends the selection back into the conversation via ``SendMessage``,
+triggering the LLM's next turn.
+
+Example::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.choice import Choice
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(Choice())
+
--- a/docs/python-sdk/fastmcp-apps-config.mdx
+++ b/docs/python-sdk/fastmcp-apps-config.mdx
@ -0,0 +1,90 @@
+---
+title: config
+sidebarTitle: config
+---
+
+# `fastmcp.apps.config`
+
+
+MCP Apps support — extension negotiation and typed UI metadata models.
+
+Provides constants and Pydantic models for the MCP Apps extension
+(io.modelcontextprotocol/ui), enabling tools and resources to carry
+UI metadata for clients that support interactive app rendering.
+
+
+## Functions
+
+### `app_config_to_meta_dict` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/config.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+app_config_to_meta_dict(app: AppConfig | dict[str, Any]) -> dict[str, Any]
+```
+
+
+Convert an AppConfig or dict to the wire-format dict for ``meta["ui"]``.
+
+
+## Classes
+
+### `ResourceCSP` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/config.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Content Security Policy for MCP App resources.
+
+Declares which external origins the app is allowed to connect to or
+load resources from.  Hosts use these declarations to build the
+``Content-Security-Policy`` header for the sandboxed iframe.
+
+
+### `ResourcePermissions` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/config.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Iframe sandbox permissions for MCP App resources.
+
+Each field, when set (typically to ``{}``), requests that the host
+grant the corresponding Permission Policy feature to the sandboxed
+iframe.  Hosts MAY honour these; apps should use JS feature detection
+as a fallback.
+
+
+### `AppConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/config.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration for MCP App tools and resources.
+
+Controls how a tool or resource participates in the MCP Apps extension.
+On tools, ``resource_uri`` and ``visibility`` specify which UI resource
+to render and where the tool appears.  On resources, those fields must
+be left unset (the resource itself is the UI).
+
+All fields use ``exclude_none`` serialization so only explicitly-set
+values appear on the wire.  Aliases match the MCP Apps wire format
+(camelCase).
+
+
+### `PrefabAppConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/config.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+App configuration for Prefab tools with sensible defaults.
+
+Like ``app=True`` but customizable. Auto-wires the Prefab renderer
+URI and merges the renderer's CSP with any additional domains you
+specify.  The renderer resource is registered automatically.
+
+Example::
+
+    @mcp.tool(app=PrefabAppConfig())  # same as app=True
+
+    @mcp.tool(app=PrefabAppConfig(
+        csp=ResourceCSP(frame_domains=["https://example.com"]),
+    ))
+
+
+**Methods:**
+
+#### `model_post_init` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/config.py#L133" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+model_post_init(self, __context: Any) -> None
+```
--- a/docs/python-sdk/fastmcp-apps-file_upload.mdx
+++ b/docs/python-sdk/fastmcp-apps-file_upload.mdx
@ -0,0 +1,144 @@
+---
+title: file_upload
+sidebarTitle: file_upload
+---
+
+# `fastmcp.apps.file_upload`
+
+
+FileUpload — a Provider that adds drag-and-drop file upload to any server.
+
+Lets users upload files directly to the server through an interactive UI,
+bypassing the LLM context window entirely. The LLM can then read and work
+with uploaded files through model-visible tools.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps import FileUpload
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(FileUpload())
+
+For custom persistence, override the storage methods::
+
+    class S3Upload(FileUpload):
+        def on_store(self, files, ctx):
+            # write to S3, return summaries
+            ...
+
+        def on_list(self, ctx):
+            # list from S3
+            ...
+
+        def on_read(self, name, ctx):
+            # read from S3
+            ...
+
+
+## Classes
+
+### `FileUpload` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/file_upload.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Provider that adds file upload capabilities to a server.
+
+Registers a drag-and-drop UI tool, a backend storage tool, and
+model-visible tools for listing and reading uploaded files.
+
+Files are scoped by MCP session and stored in memory by default.
+Override ``on_store``, ``on_list``, and ``on_read`` for custom
+persistence (filesystem, S3, database, etc.). Each method receives
+the current ``Context``, giving access to session ID, auth tokens,
+and request metadata for partitioning and authorization.
+
+**Session scoping:** The default storage uses ``ctx.session_id`` to
+isolate files by session. This works with stdio, SSE, and stateful
+HTTP transports. In **stateless HTTP** mode, each request creates a
+new session, so files won't persist across requests. For stateless
+deployments, override the storage methods to partition by a stable
+identifier from the auth context::
+
+    class UserScopedUpload(FileUpload):
+        def on_store(self, files, ctx):
+            user_id = ctx.access_token["sub"]
+            ...
+
+Example::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.file_upload import FileUpload
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(FileUpload())
+
+
+**Methods:**
+
+#### `on_store` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/file_upload.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_store(self, files: list[dict[str, Any]], ctx: Context) -> list[dict[str, Any]]
+```
+
+Store uploaded files and return summaries.
+
+**Args:**
+- `files`: List of file dicts, each with ``name``, ``size``,
+``type``, and ``data`` (base64-encoded content).
+- `ctx`: The current request context. Use for session ID,
+auth tokens, or any metadata needed for partitioning.
+
+Override this method for custom persistence. The default
+implementation stores files in memory, scoped by
+``_get_scope_key(ctx)``.
+
+**Returns:**
+- List of file summary dicts (``name``, ``type``, ``size``,
+- ``size_display``, ``uploaded_at``).
+
+
+#### `on_list` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/file_upload.py#L216" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list(self, ctx: Context) -> list[dict[str, Any]]
+```
+
+List all stored files.
+
+**Args:**
+- `ctx`: The current request context.
+
+Override this method for custom persistence. The default
+implementation returns files from the current scope.
+
+**Returns:**
+- List of file summary dicts.
+
+
+#### `on_read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/file_upload.py#L232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_read(self, name: str, ctx: Context) -> dict[str, Any]
+```
+
+Read a file's contents by name.
+
+**Args:**
+- `name`: The filename to read.
+- `ctx`: The current request context.
+
+Override this method for custom persistence. The default
+implementation reads from the current scope's in-memory store.
+Text files are decoded from base64; binary files return a
+truncated base64 preview.
+
+**Returns:**
+- Dict with file metadata and ``content`` (text) or
+- ``content_base64`` (binary preview).
+
+**Raises:**
+- `ValueError`: If the file is not found.
+
--- a/docs/python-sdk/fastmcp-apps-form.mdx
+++ b/docs/python-sdk/fastmcp-apps-form.mdx
@ -0,0 +1,69 @@
+---
+title: form
+sidebarTitle: form
+---
+
+# `fastmcp.apps.form`
+
+
+FormInput — a Provider that collects structured input from the user.
+
+Define a Pydantic model for the data you need, and ``FormInput``
+generates a form UI. The user fills it out, the submission is
+validated, and an optional callback processes the result.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from pydantic import BaseModel
+    from fastmcp import FastMCP
+    from fastmcp.apps.form import FormInput
+
+    class ShippingAddress(BaseModel):
+        street: str
+        city: str
+        state: str
+        zip_code: str
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(FormInput(model=ShippingAddress))
+
+
+## Classes
+
+### `FormInput` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/form.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Provider that collects structured input via a Pydantic model.
+
+Define a model for the data you need, and ``FormInput`` generates
+a form from it using ``Form.from_model()``. Field types, labels,
+descriptions, and validation are all derived from the model.
+
+Optionally provide an ``on_submit`` callback to process the
+validated data. The callback receives a model instance and returns
+a string that goes back to the LLM. Without a callback, the
+validated JSON is sent directly.
+
+Example::
+
+    from pydantic import BaseModel
+    from fastmcp import FastMCP
+    from fastmcp.apps.form import FormInput
+
+    class Contact(BaseModel):
+        name: str
+        email: str
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(FormInput(model=Contact))
+
+With a callback::
+
+    def save_contact(contact: Contact) -> str:
+        db.insert(contact.model_dump())
+        return f"Saved {contact.name}"
+
+    mcp.add_provider(FormInput(model=Contact, on_submit=save_contact))
+
--- a/docs/python-sdk/fastmcp-apps-generative.mdx
+++ b/docs/python-sdk/fastmcp-apps-generative.mdx
@ -0,0 +1,56 @@
+---
+title: generative
+sidebarTitle: generative
+---
+
+# `fastmcp.apps.generative`
+
+
+GenerativeUI — a Provider that adds LLM-generated UI capabilities.
+
+Registers tools and resources from ``prefab_ui.generative`` so that an
+LLM can write Prefab Python code, execute it in a sandbox, and render
+the result as a streaming interactive UI.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.generative import GenerativeUI
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(GenerativeUI())
+
+
+## Classes
+
+### `GenerativeUI` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/generative.py#L53" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Provider that adds generative UI capabilities to a server.
+
+Registers:
+
+- A ``generate_ui`` tool that accepts Prefab Python code, executes
+  it in a Pyodide sandbox, and returns the rendered PrefabApp.
+  Supports streaming via ``ontoolinputpartial``.
+- A ``components`` tool that searches the Prefab component library.
+- The generative renderer resource with CSP for Pyodide CDN access.
+
+Example::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.generative import GenerativeUI
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(GenerativeUI())
+
+
+**Methods:**
+
+#### `lifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/generative.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+lifespan(self) -> AsyncIterator[None]
+```
--- a/docs/python-sdk/fastmcp-experimental-transforms-code_mode.mdx
+++ b/docs/python-sdk/fastmcp-experimental-transforms-code_mode.mdx
@ -7,7 +7,7 @@ sidebarTitle: code_mode

 ## Classes

-### `SandboxProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `SandboxProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


 Interface for executing LLM-generated Python code in a sandbox.
@ -20,13 +20,13 @@ sandbox — never with plain ``exec()``.  Use ``MontySandboxProvider``

 **Methods:**

-#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 run(self, code: str) -> Any
 ```

-### `MontySandboxProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `MontySandboxProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


 Sandbox provider backed by `pydantic-monty`.
@ -38,16 +38,22 @@ Sandbox provider backed by `pydantic-monty`.
 ``gc_interval`` (int).  All are optional; omit a key to
 leave that limit uncapped.

+When the argument is omitted entirely, a conservative baseline
+is applied (``max_duration_secs=30``, ``max_memory=100 MB``) so
+the out-of-box configuration is not unbounded. Pass
+``limits=None`` to explicitly run without any limits, or a dict
+to set your own.
+

 **Methods:**

-#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 run(self, code: str) -> Any
 ```

-### `Search` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `Search` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


 Discovery tool factory that searches the catalog by query.
@ -64,7 +70,7 @@ Defaults to BM25 ranking.
 The LLM can override this per call.  ``None`` means no limit.


-### `GetSchemas` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L260" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `GetSchemas` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L320" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


 Discovery tool factory that returns schemas for tools by name.
@ -78,7 +84,7 @@ types, and required markers.
 ``"full"`` returns the complete JSON schema.


-### `GetTags` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L321" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `GetTags` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


 Discovery tool factory that lists tool tags from the catalog.
@ -93,7 +99,7 @@ without tags appear under ``"untagged"``.
 ``"full"`` lists all tools under each tag.


-### `ListTools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L388" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ListTools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L448" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


 Discovery tool factory that lists all tools in the catalog.
@ -106,7 +112,7 @@ Discovery tool factory that lists all tools in the catalog.
 ``"full"`` returns the complete JSON schema.


-### `CodeMode` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L437" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `CodeMode` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L497" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


 Transform that collapses all tools into discovery + execute meta-tools.
@ -123,13 +129,13 @@ environment with ``call_tool(name, params)`` in scope.

 **Methods:**

-#### `transform_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L487" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `transform_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L549" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 transform_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]
 ```

-#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L490" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L552" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 get_tool(self, name: str, call_next: GetToolNext) -> Tool | None
--- a/docs/python-sdk/fastmcp-mcp_config.mdx
+++ b/docs/python-sdk/fastmcp-mcp_config.mdx
@ -42,7 +42,7 @@ infer_transport_type_from_url(url: str | AnyUrl) -> Literal['http', 'sse']
 Infer the appropriate transport type from the given URL.


-### `update_config_file` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L361" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `update_config_file` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L363" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 update_config_file(file_path: Path, server_name: str, server_config: CanonicalMCPServerTypes) -> None
@ -167,7 +167,7 @@ from_file(cls, file_path: Path) -> Self
 Load configuration from JSON file.


-### `CanonicalMCPConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L346" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `CanonicalMCPConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L348" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


 Canonical MCP configuration format.
@ -178,7 +178,7 @@ The format is designed to be client-agnostic and extensible for future use cases

 **Methods:**

-#### `add_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L356" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `add_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 add_server(self, name: str, server: CanonicalMCPServerTypes) -> None
--- a/docs/python-sdk/fastmcp-utilities-authorization.mdx
+++ b/docs/python-sdk/fastmcp-utilities-authorization.mdx
@ -0,0 +1,70 @@
+---
+title: authorization
+sidebarTitle: authorization
+---
+
+# `fastmcp.utilities.authorization`
+
+
+Authorization checks for FastMCP components.
+
+Auth checks are callables that receive an ``AuthContext`` and return True to
+allow access or False to deny it. They can also raise ``AuthorizationError`` to
+deny with a custom message; other exceptions are masked and treated as denial.
+
+
+## Functions
+
+### `require_scopes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/authorization.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+require_scopes(*scopes: str) -> AuthCheck
+```
+
+
+Require all of the given OAuth scopes.
+
+
+### `restrict_tag` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/authorization.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+restrict_tag(tag: str) -> AuthCheck
+```
+
+
+Require scopes when the accessed component has a specific tag.
+
+
+### `run_auth_checks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/authorization.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run_auth_checks(checks: AuthCheck | list[AuthCheck], ctx: AuthContext) -> bool
+```
+
+
+Run auth checks with AND logic.
+
+
+## Classes
+
+### `AuthContext` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/authorization.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Context passed to auth check callables.
+
+**Attributes:**
+- `token`: The current access token, or None if unauthenticated.
+- `component`: The tool, resource, resource template, or prompt being accessed.
+- `tool`: Backwards-compatible alias for component when it is a Tool.
+
+
+**Methods:**
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/authorization.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self) -> Tool | None
+```
+
+Backwards-compatible access to the component as a Tool.
+
--- a/docs/python-sdk/fastmcp-utilities-json_schema.mdx
+++ b/docs/python-sdk/fastmcp-utilities-json_schema.mdx
@ -62,7 +62,7 @@ the referenced definition while preserving $defs for nested references.
 - if no resolution is needed


-### `compress_schema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema.py#L631" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `compress_schema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema.py#L645" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 compress_schema(schema: dict[str, Any], prune_params: list[str] | None = None, prune_additional_properties: bool = False, prune_titles: bool = False, dereference: bool = False) -> dict[str, Any]
--- a/docs/python-sdk/fastmcp-utilities-tasks.mdx
+++ b/docs/python-sdk/fastmcp-utilities-tasks.mdx
@ -0,0 +1,62 @@
+---
+title: tasks
+sidebarTitle: tasks
+---
+
+# `fastmcp.utilities.tasks`
+
+
+Task configuration primitives for FastMCP components.
+
+## Classes
+
+### `TaskMeta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tasks.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Metadata for task-augmented execution requests.
+
+**Attributes:**
+- `ttl`: Client-requested TTL in milliseconds. If None, uses server default.
+- `fn_key`: Docket routing key. Auto-derived from component name if None.
+
+
+### `TaskConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tasks.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration for MCP background task execution.
+
+Controls how a component handles task-augmented requests:
+
+- ``forbidden``: Component does not support task execution.
+- ``optional``: Component supports both synchronous and task execution.
+- ``required``: Component requires task execution.
+
+
+**Methods:**
+
+#### `from_bool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tasks.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_bool(cls, value: bool) -> TaskConfig
+```
+
+Convert a boolean task flag to a TaskConfig.
+
+
+#### `supports_tasks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tasks.py#L53" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+supports_tasks(self) -> bool
+```
+
+Check if this component supports task execution.
+
+
+#### `validate_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tasks.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_function(self, fn: Callable[..., Any], name: str) -> None
+```
+
+Validate that a function is compatible with this task config.
+
--- 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` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `parse_version_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 parse_version_key(version: str | None) -> VersionKey
@ -38,10 +38,10 @@ Parse a version string into a sortable key.
 - A VersionKey suitable for sorting.


-### `version_sort_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `version_sort_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
-version_sort_key(component: FastMCPComponent) -> VersionKey
+version_sort_key(component: FastMCPComponent) -> tuple[VersionKey, str]
 ```


@ -49,14 +49,22 @@ Get a sort key for a component based on its version.

 Use with sorted() or max() to order components by version.

+The key is a `(VersionKey, raw)` tuple. The `VersionKey` orders by PEP 440
+semantics (or lexicographically for non-PEP 440 strings); the raw version
+string is a deterministic tie-breaker so that two components whose versions
+are PEP 440-equivalent but spelled differently (e.g. `"1"` and `"1.0"`) are
+ordered reproducibly instead of by registration order. The raw tie-breaker
+only affects equivalent-version ties and never the primary version order,
+so range/equality matching (which uses `VersionKey` directly) is unchanged.
+
 **Args:**
 - `component`: The component to get a sort key for.

 **Returns:**
- A sortable VersionKey.
+- A deterministic, sortable `(VersionKey, raw)` tuple.


-### `compare_versions` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L222" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `compare_versions` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 compare_versions(a: str | None, b: str | None) -> int
@ -73,7 +81,7 @@ Compare two version strings.
 - -1 if a &lt; b, 0 if a == b, 1 if a &gt; b.


-### `is_version_greater` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `is_version_greater` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 is_version_greater(a: str | None, b: str | None) -> bool
@ -90,7 +98,7 @@ Check if version a is greater than version b.
 - True if a > b, False otherwise.


-### `max_version` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `max_version` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 max_version(a: str | None, b: str | None) -> str | None
@ -107,7 +115,7 @@ Return the greater of two versions.
 - The greater version, or None if both are None.


-### `min_version` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L274" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `min_version` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L289" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 min_version(a: str | None, b: str | None) -> str | None
@ -124,7 +132,7 @@ Return the lesser of two versions.
 - The lesser version, or None if both are None.


-### `dedupe_with_versions` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L291" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `dedupe_with_versions` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L306" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 dedupe_with_versions(components: Sequence[C], key_fn: Callable[[C], str]) -> list[C]
@ -159,11 +167,18 @@ match any spec.
 - `gte`: If set, only versions >= this value match.
 - `lt`: If set, only versions < this value match.
 - `eq`: If set, only this exact version matches (gte/lt ignored).
+Matching is PEP 440-normalized and `v`-prefix insensitive, so
+`eq="v1.0"` matches a component versioned `"1.0"`, and `eq="1.0"`
+matches `"1"` (PEP 440 treats `1` and `1.0` as the same version).
+If a server registers two PEP 440-equivalent spellings of the
+same component (e.g. both `"1"` and `"1.0"`), they are the same
+version under this spec; selection among them is deterministic
+(see `version_sort_key`), not registration-order dependent.


 **Methods:**

-#### `matches` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `matches` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 matches(self, version: str | None) -> bool
@ -182,7 +197,7 @@ from version-specific rules.
 - True if the version matches the spec.


-#### `intersect` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `intersect` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

 ```python
 intersect(self, other: VersionSpec | None) -> VersionSpec
@ -201,7 +216,7 @@ the intersection validates "1.0" is in range and returns the exact spec.
 - A VersionSpec that matches only versions satisfying both specs.


-### `VersionKey` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `VersionKey` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


 A comparable version key that handles None, PEP 440 versions, and strings.