diff --git a/README.md b/README.md index 68c39936b..da58d8987 100644 --- a/README.md +++ b/README.md @@ -43,21 +43,41 @@ if __name__ == "__main__": ## Why FastMCP -MCP lets you give agents access to your tools and data. But building an effective MCP server is harder than it looks. +The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) lets you give agents access to your tools and data. But building an effective MCP application is harder than it looks. -Give your agent too much—hundreds of tools, verbose responses—and it gets overwhelmed. Give it too little and it can't do its job. The protocol itself is complex, with layers of serialization, validation, and error handling that have nothing to do with your business logic. And the spec keeps evolving; what worked last month might already need updating. +FastMCP handles all of it. Declare a tool with a Python function, and the schema, validation, and documentation are generated automatically. Connect to a server with a URL, and transport negotiation, authentication, and protocol lifecycle are managed for you. You focus on your logic, and the MCP part just works: **with FastMCP, best practices are built in.** -The real challenge isn't implementing the protocol. It's delivering **the right information at the right time**. +**That's why FastMCP is the standard framework for working with MCP.** FastMCP 1.0 was incorporated into the official MCP SDK in 2024. Today, the actively maintained standalone project is downloaded a million times a day, and some version of FastMCP powers 70% of MCP servers across all languages. -That's the problem FastMCP solves—and why it's become the standard. FastMCP 1.0 was incorporated into the official MCP SDK in 2024. Today, the actively maintained standalone project is downloaded a million times a day, and some version of FastMCP powers 70% of MCP servers across all languages. +FastMCP has three pillars: -The framework is built on three abstractions that map to the decisions you actually need to make: + + + + + + +
+ +Servers +
Servers + +
Expose tools, resources, and prompts to LLMs. +		 + +Apps +
Apps + +
Give your tools interactive UIs rendered directly in the conversation. +		 + +Clients +
Clients + +
Connect to any MCP server — local or remote, programmatic or CLI. +
-- **Components** are what you expose: tools, resources, and prompts. Wrap a Python function, and FastMCP handles the schema, validation, and docs. -- **Providers** are where components come from: decorated functions, files on disk, OpenAPI specs, remote servers—your logic can live anywhere. -- **Transforms** shape what clients see: namespacing, filtering, authorization, versioning. The same server can present differently to different users. - -These compose cleanly, so complex patterns don't require complex code. And because FastMCP is opinionated about the details, like serialization, error handling, and protocol compliance, **best practices are the path of least resistance**. You focus on your logic; the MCP part just works. +**[Servers](https://gofastmcp.com/servers/server)** wrap your Python functions into MCP-compliant tools, resources, and prompts. **[Clients](https://gofastmcp.com/clients/client)** connect to any server with full protocol support. And **[Apps](https://gofastmcp.com/apps/overview)** give your tools interactive UIs rendered directly in the conversation. **Move fast and make things.** diff --git a/docs/apps/low-level.mdx b/docs/apps/low-level.mdx new file mode 100644 index 000000000..a908dff4b --- /dev/null +++ b/docs/apps/low-level.mdx @@ -0,0 +1,303 @@ +--- +title: Low-Level API +sidebarTitle: Low-Level API +description: Integrate directly with the MCP Apps extension to build interactive tool UIs. +icon: code +tag: NEW +--- + +import { VersionBadge } from '/snippets/version-badge.mdx' + + + +The [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps) (`io.modelcontextprotocol/ui`) lets tools return interactive UIs — an HTML page rendered in a sandboxed iframe inside the host client. Instead of returning plain text or JSON, a tool can show a chart, a form, an image viewer, or anything you can build with HTML and JavaScript. + +This page covers the low-level extension API directly. FastMCP provides typed models for app configuration, automatic `ui://` resource handling, and CSP/permission management. + +## How It Works + +An MCP App has two parts: + +1. A **tool** that does the work and returns data +2. A **`ui://` resource** containing the HTML that renders that data + +The tool declares which resource to use via `AppConfig`. When the host calls the tool, it also fetches the linked resource, renders it in a sandboxed iframe, and pushes the tool result into the app via `postMessage`. The app can also call tools back, enabling interactive workflows. + +```python +import json + +from fastmcp import FastMCP +from fastmcp.server.apps import AppConfig, ResourceCSP + +mcp = FastMCP("My App Server") + +# The tool does the work +@mcp.tool(app=AppConfig(resource_uri="ui://my-app/view.html")) +def generate_chart(data: list[float]) -> str: + return json.dumps({"values": data}) + +# The resource provides the UI +@mcp.resource("ui://my-app/view.html") +def chart_view() -> str: + return "..." +``` + +## AppConfig + +`AppConfig` controls how a tool or resource participates in the Apps extension. Import it from `fastmcp.server.apps`: + +```python +from fastmcp.server.apps import AppConfig +``` + +On **tools**, you'll typically set `resource_uri` to point to the UI resource: + +```python +@mcp.tool(app=AppConfig(resource_uri="ui://my-app/view.html")) +def my_tool() -> str: + return "result" +``` + +You can also pass a raw dict with camelCase keys, matching the wire format: + +```python +@mcp.tool(app={"resourceUri": "ui://my-app/view.html"}) +def my_tool() -> str: + return "result" +``` + +### Tool Visibility + +The `visibility` field controls where a tool appears: + +- `["model"]` — visible to the LLM (the default behavior) +- `["app"]` — only callable from within the app UI, hidden from the LLM +- `["model", "app"]` — both + +This is useful when you have tools that only make sense as part of the app's interactive flow, not as standalone LLM actions. + +```python +@mcp.tool( + app=AppConfig( + resource_uri="ui://my-app/view.html", + visibility=["app"], + ) +) +def refresh_data() -> str: + """Only callable from the app UI, not by the LLM.""" + return fetch_latest() +``` + +### AppConfig Fields + +| Field | Type | Description | +|-------|------|-------------| +| `resource_uri` | `str` | URI of the UI resource. Tools only. | +| `visibility` | `list[str]` | Where the tool appears: `"model"`, `"app"`, or both. Tools only. | +| `csp` | `ResourceCSP` | Content Security Policy for the iframe. | +| `permissions` | `ResourcePermissions` | Iframe sandbox permissions. | +| `domain` | `str` | Stable sandbox origin for the iframe. | +| `prefers_border` | `bool` | Whether the UI prefers a visible border. | + + +On **resources**, `resource_uri` and `visibility` must not be set — the resource *is* the UI. Use `AppConfig` on resources only for `csp`, `permissions`, and other display settings. + + +## UI Resources + +Resources using the `ui://` scheme are automatically served with the MIME type `text/html;profile=mcp-app`. You don't need to set this manually. + +```python +@mcp.resource("ui://my-app/view.html") +def my_view() -> str: + return "..." +``` + +The HTML can be anything — a full single-page app, a simple display, or a complex interactive tool. The host renders it in a sandboxed iframe and establishes a `postMessage` channel for communication. + +### Writing the App HTML + +Your HTML app communicates with the host using the [`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps) JavaScript SDK. The simplest approach is to load it from a CDN: + +```html + +``` + +The `App` object provides: + +- **`app.ontoolresult`** — callback that receives tool results pushed by the host +- **`app.callServerTool({name, arguments})`** — call a tool on the server from within the app +- **`app.onhostcontextchanged`** — callback for host context changes (e.g., safe area insets) +- **`app.getHostContext()`** — get current host context + + +If your HTML loads external scripts, styles, or makes API calls, you need to declare those domains in the CSP configuration. See [Security](#security) below. + + +## Security + +Apps run in sandboxed iframes with a deny-by-default Content Security Policy. By default, only inline scripts and styles are allowed — no external network access. + +### Content Security Policy + +If your app needs to load external resources (CDN scripts, API calls, embedded iframes), declare the allowed domains with `ResourceCSP`: + +```python +from fastmcp.server.apps import AppConfig, ResourceCSP + +@mcp.resource( + "ui://my-app/view.html", + app=AppConfig( + csp=ResourceCSP( + resource_domains=["https://unpkg.com", "https://cdn.example.com"], + connect_domains=["https://api.example.com"], + ) + ), +) +def my_view() -> str: + return "..." +``` + +| CSP Field | Controls | +|-----------|----------| +| `connect_domains` | `fetch`, XHR, WebSocket (`connect-src`) | +| `resource_domains` | Scripts, images, styles, fonts (`script-src`, etc.) | +| `frame_domains` | Nested iframes (`frame-src`) | +| `base_uri_domains` | Document base URI (`base-uri`) | + +### Permissions + +If your app needs browser capabilities like camera or clipboard access, request them via `ResourcePermissions`: + +```python +from fastmcp.server.apps import AppConfig, ResourcePermissions + +@mcp.resource( + "ui://my-app/view.html", + app=AppConfig( + permissions=ResourcePermissions( + camera={}, + clipboard_write={}, + ) + ), +) +def my_view() -> str: + return "..." +``` + +Hosts may or may not grant these permissions. Your app should use JavaScript feature detection as a fallback. + +## Example: QR Code Server + +This example creates a tool that generates QR codes and an app that renders them as images. It's based on the [official MCP Apps example](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/qr-server). Requires the `qrcode[pil]` package. + +```python expandable +import base64 +import io + +import qrcode +from mcp import types + +from fastmcp import FastMCP +from fastmcp.server.apps import AppConfig, ResourceCSP +from fastmcp.tools import ToolResult + +mcp = FastMCP("QR Code Server") + +VIEW_URI = "ui://qr-server/view.html" + + +@mcp.tool(app=AppConfig(resource_uri=VIEW_URI)) +def generate_qr(text: str = "https://gofastmcp.com") -> ToolResult: + """Generate a QR code from text.""" + qr = qrcode.QRCode(version=1, box_size=10, border=4) + qr.add_data(text) + qr.make(fit=True) + + img = qr.make_image() + buffer = io.BytesIO() + img.save(buffer, format="PNG") + b64 = base64.b64encode(buffer.getvalue()).decode() + + return ToolResult( + content=[types.ImageContent(type="image", data=b64, mimeType="image/png")] + ) + + +@mcp.resource( + VIEW_URI, + app=AppConfig(csp=ResourceCSP(resource_domains=["https://unpkg.com"])), +) +def view() -> str: + """Interactive QR code viewer.""" + return """\ + + + + + + + +
+ + +""" +``` + +The tool generates a QR code as a base64 PNG. The resource loads the MCP Apps JS SDK from unpkg (declared in the CSP), listens for tool results, and renders the image. The host wires them together — when the LLM calls `generate_qr`, the QR code appears in an interactive frame inside the conversation. + +## Checking Client Support + +Not all hosts support the Apps extension. You can check at runtime using the tool's [context](/servers/context): + +```python +from fastmcp import Context +from fastmcp.server.apps import AppConfig, UI_EXTENSION_ID + +@mcp.tool(app=AppConfig(resource_uri="ui://my-app/view.html")) +async def my_tool(ctx: Context) -> str: + if ctx.client_supports_extension(UI_EXTENSION_ID): + # Return data optimized for UI rendering + return rich_response() + else: + # Fall back to plain text + return plain_text_response() +``` diff --git a/docs/apps/overview.mdx b/docs/apps/overview.mdx new file mode 100644 index 000000000..07b1d8bc0 --- /dev/null +++ b/docs/apps/overview.mdx @@ -0,0 +1,31 @@ +--- +title: Apps +sidebarTitle: Overview +description: Give your tools interactive UIs rendered directly in the conversation. +icon: grid-2 +tag: NEW +--- + +import { VersionBadge } from '/snippets/version-badge.mdx' + + + +MCP Apps let your tools return interactive UIs — rendered in a sandboxed iframe right inside the host client's conversation. Instead of returning plain text or JSON, a tool can show a chart, a form, an image viewer, or anything you can build with HTML and JavaScript. + +FastMCP implements the [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps), so you can start building apps today. FastMCP 3.1 will introduce a full Python-native app framework that makes building rich UIs dramatically simpler — no HTML or JavaScript required. + +## What's Available Today + +FastMCP provides typed models and helpers for working with the MCP Apps extension directly: + +- **`AppConfig`** to link tools to UI resources and control visibility +- **`ui://` resources** that automatically serve HTML with the correct MIME type +- **`ResourceCSP`** and **`ResourcePermissions`** for security and sandboxing + +This is the [low-level API](/apps/low-level) — you write the HTML yourself and wire up communication with the host via the `@modelcontextprotocol/ext-apps` JavaScript SDK. It gives you full control over the UI. + +## What's Coming in 3.1 + +FastMCP 3.1 will ship a Python-native app framework that lets you build interactive UIs entirely in Python. Define layouts, handle events, and manage state without writing any HTML or JavaScript — FastMCP generates the app for you. + +Stay tuned. In the meantime, the [low-level API](/apps/low-level) is ready to use. diff --git a/docs/assets/images/apps-card.png b/docs/assets/images/apps-card.png new file mode 100644 index 000000000..1704c46bb Binary files /dev/null and b/docs/assets/images/apps-card.png differ diff --git a/docs/assets/images/clients-card.png b/docs/assets/images/clients-card.png new file mode 100644 index 000000000..f9b36cf9b Binary files /dev/null and b/docs/assets/images/clients-card.png differ diff --git a/docs/assets/images/servers-card.png b/docs/assets/images/servers-card.png new file mode 100644 index 000000000..534779e96 Binary files /dev/null and b/docs/assets/images/servers-card.png differ diff --git a/docs/changelog.mdx b/docs/changelog.mdx index cf25fdfec..90f26bddb 100644 --- a/docs/changelog.mdx +++ b/docs/changelog.mdx @@ -2,6 +2,7 @@ title: "Changelog" icon: "list-check" rss: true +tag: NEW --- diff --git a/docs/clients/auth/cimd.mdx b/docs/clients/auth/cimd.mdx index 6980c66f2..c1f92d1c4 100644 --- a/docs/clients/auth/cimd.mdx +++ b/docs/clients/auth/cimd.mdx @@ -3,6 +3,7 @@ title: CIMD Authentication sidebarTitle: CIMD description: Use Client ID Metadata Documents for verifiable, domain-based client identity. icon: id-badge +tag: NEW --- import { VersionBadge } from "/snippets/version-badge.mdx" diff --git a/docs/clients/generate-cli.mdx b/docs/clients/generate-cli.mdx index 4d05e0515..b0faaefb0 100644 --- a/docs/clients/generate-cli.mdx +++ b/docs/clients/generate-cli.mdx @@ -3,6 +3,7 @@ title: Generate CLI sidebarTitle: Generate CLI description: Turn any MCP server into a standalone, typed command-line tool. icon: wand-magic-sparkles +tag: NEW --- import { VersionBadge } from '/snippets/version-badge.mdx' diff --git a/docs/development/upgrade-guide.mdx b/docs/development/upgrade-guide.mdx index 70a60b830..e20f2c76c 100644 --- a/docs/development/upgrade-guide.mdx +++ b/docs/development/upgrade-guide.mdx @@ -3,6 +3,7 @@ title: Upgrade Guide sidebarTitle: Upgrade Guide description: Migration instructions for upgrading between FastMCP versions icon: up +tag: NEW --- This guide covers breaking changes and migration steps when upgrading FastMCP. diff --git a/docs/docs.json b/docs/docs.json index fc5499d5a..fe4abcdce 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -89,8 +89,7 @@ "getting-started/welcome", "getting-started/installation", "development/upgrade-guide", - "getting-started/quickstart", - "updates" + "getting-started/quickstart" ] }, { @@ -98,6 +97,7 @@ "pages": [ "servers/server", { + "collapsed": true, "group": "Core Components", "icon": "toolbox", "pages": [ @@ -108,7 +108,9 @@ ] }, { + "collapsed": true, "group": "Features", + "tag": "NEW", "icon": "stars", "pages": [ "servers/tasks", @@ -127,6 +129,36 @@ ] }, { + "collapsed": true, + "group": "Providers", + "tag": "NEW", + "icon": "layer-group", + "pages": [ + "servers/providers/overview", + "servers/providers/local", + "servers/providers/filesystem", + "servers/providers/proxy", + "servers/providers/skills", + "servers/providers/custom", + "servers/providers/mounting" + ] + }, + { + "collapsed": true, + "group": "Transforms", + "tag": "NEW", + "icon": "wand-magic-sparkles", + "pages": [ + "servers/transforms/transforms", + "servers/transforms/namespace", + "servers/transforms/tool-transformation", + "servers/visibility", + "servers/transforms/resources-as-tools", + "servers/transforms/prompts-as-tools" + ] + }, + { + "collapsed": true, "group": "Authentication", "icon": "key", "pages": [ @@ -138,40 +170,46 @@ "servers/auth/full-oauth-server" ] }, - "servers/authorization" + "servers/authorization", + { + "collapsed": true, + "group": "Deployment", + "icon": "rocket", + "pages": [ + "deployment/running-server", + "deployment/http", + "deployment/prefect-horizon", + "deployment/server-configuration", + "patterns/cli", + "patterns/testing" + ] + } ] }, { - "group": "MCP Providers", + "group": "Apps", "pages": [ - "servers/providers/overview", - "servers/providers/local", - "servers/providers/filesystem", - "servers/providers/proxy", - "servers/providers/skills", - "servers/providers/custom", - "servers/providers/mounting" - ] - }, - { - "group": "MCP Transforms", - "pages": [ - "servers/transforms/transforms", - "servers/transforms/namespace", - "servers/transforms/tool-transformation", - "servers/visibility", - "servers/transforms/resources-as-tools", - "servers/transforms/prompts-as-tools" + "apps/overview", + "apps/low-level" ] }, { "group": "Clients", "pages": [ "clients/client", - "clients/cli", - "clients/generate-cli", "clients/transports", { + "collapsed": true, + "group": "CLI", + "tag": "NEW", + "icon": "terminal", + "pages": [ + "clients/cli", + "clients/generate-cli" + ] + }, + { + "collapsed": true, "group": "Core Operations", "icon": "toolbox", "pages": [ @@ -181,6 +219,7 @@ ] }, { + "collapsed": true, "group": "Handlers", "icon": "hand", "pages": [ @@ -194,7 +233,9 @@ ] }, { + "collapsed": true, "group": "Authentication", + "tag": "NEW", "icon": "key", "pages": [ "clients/auth/oauth", @@ -204,17 +245,6 @@ } ] }, - { - "group": "Deployment", - "pages": [ - "deployment/running-server", - "deployment/http", - "deployment/prefect-horizon", - "deployment/server-configuration", - "patterns/cli", - "patterns/testing" - ] - }, { "group": "Integrations", "pages": [ @@ -240,6 +270,7 @@ ] }, { + "collapsed": true, "group": "Web Frameworks", "icon": "code", "pages": [ @@ -279,6 +310,7 @@ "development/contributing", "development/tests", "development/releases", + "updates", "changelog", "patterns/contrib" ] @@ -667,7 +699,7 @@ "icon": "code" } ], - "version": "v3.0.0 (rc 1)" + "version": "v3.0.0 (rc 2)" }, { "dropdowns": [ diff --git a/docs/getting-started/welcome.mdx b/docs/getting-started/welcome.mdx index 5b1fd66e2..4f5d8af9e 100644 --- a/docs/getting-started/welcome.mdx +++ b/docs/getting-started/welcome.mdx @@ -1,8 +1,9 @@ --- -title: "Welcome to FastMCP 3.0!" +title: "Welcome to FastMCP" sidebarTitle: "Welcome!" -description: The fast, Pythonic way to build MCP servers and clients. +description: The fast, Pythonic way to build MCP servers, clients, and applications. icon: hand-wave +mode: center --- -**FastMCP is the standard framework for building MCP applications.** The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) provides a standardized way to connect LLMs to tools and data, and FastMCP makes it production-ready with clean, Pythonic code: +**FastMCP is the standard framework for building MCP applications.** The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) connects LLMs to tools and data. FastMCP gives you everything you need to go from idea to production — build servers that expose capabilities, connect clients to any MCP service, and give your tools interactive UIs: ```python {1} from fastmcp import FastMCP @@ -35,32 +36,35 @@ if __name__ == "__main__": mcp.run() ``` - -**This documentation is for FastMCP 3.0**, which is currently a release candidate. For the 2.x release, see the [FastMCP 2.0 documentation](/v2/getting-started/welcome). - - -FastMCP is made with 💙 by [Prefect](https://www.prefect.io/). ## Move Fast and Make Things -The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) lets you give agents access to your tools and data. But building an effective MCP server is harder than it looks. +The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) lets you give agents access to your tools and data. But building an effective MCP application is harder than it looks. -Give your agent too much—hundreds of tools, verbose responses—and it gets overwhelmed. Give it too little and it can't do its job. The protocol itself is complex, with layers of serialization, validation, and error handling that have nothing to do with your business logic. And the spec keeps evolving; what worked last month might already need updating. +FastMCP handles all of it. Declare a tool with a Python function, and the schema, validation, and documentation are generated automatically. Connect to a server with a URL, and transport negotiation, authentication, and protocol lifecycle are managed for you. You focus on your logic, and the MCP part just works: **with FastMCP, best practices are built in.** -The real challenge isn't implementing the protocol. It's delivering **the right information at the right time**. +**That's why FastMCP is the standard framework for working with MCP.** FastMCP 1.0 was incorporated into the official MCP SDK in 2024. Today, the actively maintained standalone project is downloaded a million times a day, and some version of FastMCP powers 70% of MCP servers across all languages. -That's the problem FastMCP solves—and why it's become the standard. FastMCP 1.0 was incorporated into the official MCP SDK in 2024. Today, the actively maintained standalone project is downloaded a million times a day, and some version of FastMCP powers 70% of MCP servers across all languages. +FastMCP has three pillars: -The framework is built on three abstractions that map to the decisions you actually need to make: + + + Expose tools, resources, and prompts to LLMs. + + + Give your tools interactive UIs rendered directly in the conversation. + + + Connect to any MCP server — local or remote, programmatic or CLI. + + -- **[Components](/servers/tools)** are what you expose: tools, resources, and prompts. Wrap a Python function, and FastMCP handles the schema, validation, and docs. -- **[Providers](/servers/providers/overview)** are where components come from: decorated functions, files on disk, OpenAPI specs, remote servers—your logic can live anywhere. -- **[Transforms](/servers/transforms/transforms)** shape what clients see: namespacing, filtering, authorization, versioning. The same server can present differently to different users. - -These compose cleanly, so complex patterns don't require complex code. And because FastMCP is opinionated about the details, like serialization, error handling, and protocol compliance, **best practices are the path of least resistance**. You focus on your logic; the MCP part just works. +**[Servers](/servers/server)** wrap your Python functions into MCP-compliant tools, resources, and prompts. **[Clients](/clients/client)** connect to any server with full protocol support. And **[Apps](/apps/overview)** give your tools interactive UIs rendered directly in the conversation. Ready to build? Start with the [installation guide](/getting-started/installation) or jump straight to the [quickstart](/getting-started/quickstart). When you're ready to deploy, [Prefect Horizon](https://www.prefect.io/horizon) offers free hosting for FastMCP users. +FastMCP is made with 💙 by [Prefect](https://www.prefect.io/). + **This documentation reflects FastMCP's `main` branch**, meaning it always reflects the latest development version. Features are generally marked with version badges (e.g. `New in version: 3.0.0`) to indicate when they were introduced. Note that this may include features that are not yet released. @@ -71,7 +75,7 @@ The FastMCP documentation is available in multiple LLM-friendly formats: ### MCP Server -The FastMCP docs are accessible via MCP! The server URL is `https://gofastmcp.com/mcp`. +The FastMCP docs are accessible via MCP! The server URL is `https://gofastmcp.com/mcp`. In fact, you can use FastMCP to search the FastMCP docs: @@ -82,7 +86,7 @@ from fastmcp import Client async def main(): async with Client("https://gofastmcp.com/mcp") as client: result = await client.call_tool( - name="SearchFastMcp", + name="SearchFastMcp", arguments={"query": "deploy a FastMCP server"} ) print(result)