π The fast, Pythonic way to build MCP servers and clients.
chore: Update SDK documentation (#3615)
marvin-context-protocol[bot]145dbbfb4c3b
diff --git a/docs/docs.json b/docs/docs.jsonindex 91fef7409..1770ff0a1 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -368,6 +368,14 @@"python-sdk/fastmcp-settings","python-sdk/fastmcp-telemetry","python-sdk/fastmcp-types",+ {+ "group": "fastmcp.apps",+ "pages": [+ "python-sdk/fastmcp-apps-__init__",+ "python-sdk/fastmcp-apps-app",+ "python-sdk/fastmcp-apps-config"+ ]+ },{"group": "fastmcp.cli","pages": [@@ -742,6 +750,7 @@}]},+ "python-sdk/fastmcp-utilities-mime",{"group": "openapi","pages": [diff --git a/docs/python-sdk/fastmcp-apps-__init__.mdx b/docs/python-sdk/fastmcp-apps-__init__.mdxnew file mode 100644index 000000000..5f69a4b59--- /dev/null+++ b/docs/python-sdk/fastmcp-apps-__init__.mdx@@ -0,0 +1,16 @@+---+title: __init__+sidebarTitle: __init__+---++# `fastmcp.apps`+++FastMCP Apps β interactive UIs for MCP tools.++This package contains the app-related components:++- ``FastMCPApp`` β composable provider for interactive apps with backend tools+- ``AppConfig`` β configuration for MCP App tools and resources+- ``ResourceCSP`` / ``ResourcePermissions`` β security configuration+diff --git a/docs/python-sdk/fastmcp-apps-app.mdx b/docs/python-sdk/fastmcp-apps-app.mdxnew file mode 100644index 000000000..93f93f3e3--- /dev/null+++ 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) -> dict:+ return {"name": name, "email": email}++ server = FastMCP("Platform")+ server.add_provider(app)+++## Classes++### `FastMCPApp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/apps/app.py#L122" 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/src/fastmcp/apps/app.py#L144" 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/src/fastmcp/apps/app.py#L156" 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/src/fastmcp/apps/app.py#L167" 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/src/fastmcp/apps/app.py#L228" 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/src/fastmcp/apps/app.py#L243" 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/src/fastmcp/apps/app.py#L257" 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/src/fastmcp/apps/app.py#L346" 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/src/fastmcp/apps/app.py#L397" 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/src/fastmcp/apps/app.py#L405" 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.+diff --git a/docs/python-sdk/fastmcp-apps-config.mdx b/docs/python-sdk/fastmcp-apps-config.mdxnew file mode 100644index 000000000..aba84b288--- /dev/null+++ b/docs/python-sdk/fastmcp-apps-config.mdx@@ -0,0 +1,64 @@+---+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/src/fastmcp/apps/config.py#L117" 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/src/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/src/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/src/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).+diff --git a/docs/python-sdk/fastmcp-server-app.mdx b/docs/python-sdk/fastmcp-server-app.mdxindex 7e1532394..7f99ecb53 100644--- a/docs/python-sdk/fastmcp-server-app.mdx+++ b/docs/python-sdk/fastmcp-server-app.mdx@@ -6,141 +6,8 @@ sidebarTitle: app# `fastmcp.server.app`-FastMCPApp β a Provider that represents a composable MCP application.+Backward-compatible re-exports from fastmcp.apps.app.-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) -> dict:- return {"name": name, "email": email}-- server = FastMCP("Platform")- server.add_provider(app)---## Classes--### `FastMCPApp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/app.py#L122" 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/src/fastmcp/server/app.py#L144" 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/src/fastmcp/server/app.py#L156" 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/src/fastmcp/server/app.py#L167" 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/src/fastmcp/server/app.py#L228" 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/src/fastmcp/server/app.py#L243" 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/src/fastmcp/server/app.py#L257" 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/src/fastmcp/server/app.py#L346" 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/src/fastmcp/server/app.py#L397" 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/src/fastmcp/server/app.py#L405" 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.+.. deprecated:: 3.2.0+ Import from ``fastmcp.apps.app`` or ``fastmcp`` instead.diff --git a/docs/python-sdk/fastmcp-server-apps.mdx b/docs/python-sdk/fastmcp-server-apps.mdxindex 00e53eafe..df7d64d44 100644--- a/docs/python-sdk/fastmcp-server-apps.mdx+++ b/docs/python-sdk/fastmcp-server-apps.mdx@@ -6,81 +6,8 @@ sidebarTitle: apps# `fastmcp.server.apps`-MCP Apps support β extension negotiation and typed UI metadata models.+Backward-compatible re-exports from fastmcp.apps.-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/src/fastmcp/server/apps.py#L115" 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"]``.---### `resolve_ui_mime_type` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/apps.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>--```python-resolve_ui_mime_type(uri: str, explicit_mime_type: str | None) -> str | None-```---Return the appropriate MIME type for a resource URI.--For ``ui://`` scheme resources, defaults to ``UI_MIME_TYPE`` when no-explicit MIME type is provided. This ensures UI resources are correctly-identified regardless of how they're registered (via FastMCP.resource,-the standalone @resource decorator, or resource templates).--**Args:**-- `uri`: The resource URI string-- `explicit_mime_type`: The MIME type explicitly provided by the user--**Returns:**-- The resolved MIME type (explicit value, UI default, or None)---## Classes--### `ResourceCSP` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/apps.py#L18" 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/src/fastmcp/server/apps.py#L50" 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/src/fastmcp/server/apps.py#L77" 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).+.. deprecated:: 3.2.0+ Import from ``fastmcp.apps`` instead.diff --git a/docs/python-sdk/fastmcp-server-auth-providers-google.mdx b/docs/python-sdk/fastmcp-server-auth-providers-google.mdxindex b9568dbf9..05f2400b0 100644--- a/docs/python-sdk/fastmcp-server-auth-providers-google.mdx+++ b/docs/python-sdk/fastmcp-server-auth-providers-google.mdx@@ -34,22 +34,30 @@ Example:Token verifier for Google OAuth tokens.-Google OAuth tokens are opaque (not JWTs), so we verify them-by calling Google's tokeninfo API to check if they're valid and get user info.+Google OAuth tokens are opaque (not JWTs), so we verify them by calling+Google's tokeninfo endpoint with the access token as a query parameter.+This returns the OAuth app ID (``aud``), granted scopes, and expiry time.+User profile data (name, picture, etc.) is fetched separately from the+v2 userinfo endpoint when the token is valid.**Methods:**-#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/google.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/google.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonverify_token(self, token: str) -> AccessToken | None```-Verify Google OAuth token by calling Google's tokeninfo API.+Verify a Google OAuth token using the tokeninfo endpoint.+Calls ``https://oauth2.googleapis.com/tokeninfo?access_token=TOKEN``+to validate the token and retrieve the OAuth app ID (``aud``), granted+scopes, and expiry time. On success, fetches user profile data from+the v2 userinfo endpoint to populate name, picture, and locale claims.-### `GoogleProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/google.py#L190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>++### `GoogleProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/google.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>Complete Google OAuth provider for FastMCP.diff --git a/docs/python-sdk/fastmcp-server-context.mdx b/docs/python-sdk/fastmcp-server-context.mdxindex 58a916faf..78371e393 100644--- a/docs/python-sdk/fastmcp-server-context.mdx+++ b/docs/python-sdk/fastmcp-server-context.mdx@@ -319,7 +319,7 @@ request context) or when the client did not advertise the extension.Example::- from fastmcp.server.apps import UI_EXTENSION_ID+ from fastmcp.apps.config import UI_EXTENSION_ID@mcp.toolasync def my_tool(ctx: Context) -> str:diff --git a/docs/python-sdk/fastmcp-utilities-mime.mdx b/docs/python-sdk/fastmcp-utilities-mime.mdxnew file mode 100644index 000000000..b823d447b--- /dev/null+++ b/docs/python-sdk/fastmcp-utilities-mime.mdx@@ -0,0 +1,35 @@+---+title: mime+sidebarTitle: mime+---++# `fastmcp.utilities.mime`+++MIME type constants and helpers for MCP Apps UI resources.++This module has no dependencies on the server or resource packages,+so it can be safely imported from anywhere.+++## Functions++### `resolve_ui_mime_type` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/mime.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>++```python+resolve_ui_mime_type(uri: str, explicit_mime_type: str | None) -> str | None+```+++Return the appropriate MIME type for a resource URI.++For ``ui://`` scheme resources, defaults to ``UI_MIME_TYPE`` when no+explicit MIME type is provided.++**Args:**+- `uri`: The resource URI string+- `explicit_mime_type`: The MIME type explicitly provided by the user++**Returns:**+- The resolved MIME type (explicit value, UI default, or None)+