mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-09 23:29:10 +02:00
187 lines
8.9 KiB
Text
187 lines
8.9 KiB
Text
---
|
|
title: Quickstart
|
|
sidebarTitle: Quickstart
|
|
description: Build your first MCP app in under a minute.
|
|
icon: rocket
|
|
tag: NEW
|
|
---
|
|
|
|
import { VersionBadge } from '/snippets/version-badge.mdx'
|
|
|
|
<VersionBadge version="3.2.0" />
|
|
|
|
MCP tools normally return text. FastMCP apps return interactive UIs rendered directly in the conversation: charts, tables, forms, dashboards. The easiest way to build one is with [Prefab UI](https://prefab.prefect.io), a Python component library designed for exactly this. You describe the UI in Python; Prefab compiles it to something the host can render.
|
|
|
|
This tutorial builds a working app from scratch.
|
|
|
|
## Setup
|
|
|
|
Install FastMCP with the `apps` extra, which pulls in Prefab UI:
|
|
|
|
```bash
|
|
pip install "fastmcp[apps]"
|
|
```
|
|
|
|
## A Tool That Returns a UI
|
|
|
|
When your tool has something to *show* (a table of results, a chart, a status dashboard) you can return an interactive UI instead of text. Build the visualization with Prefab components, return it from your tool, and set `app=True` so FastMCP knows to render it. The user sees a live, interactive widget right in the conversation instead of a wall of JSON.
|
|
|
|
Create `server.py`:
|
|
|
|
```python
|
|
from collections import Counter
|
|
|
|
from prefab_ui.app import PrefabApp
|
|
from prefab_ui.components import Column, Grid, Heading, DataTable, DataTableColumn
|
|
from prefab_ui.components.charts import PieChart
|
|
from fastmcp import FastMCP
|
|
|
|
mcp = FastMCP("My First App")
|
|
|
|
|
|
@mcp.tool(app=True)
|
|
def team_directory() -> PrefabApp:
|
|
"""Browse the team directory."""
|
|
members = [
|
|
{"name": "Alice Chen", "role": "Staff Engineer", "office": "San Francisco"},
|
|
{"name": "Bob Martinez", "role": "Lead Designer", "office": "New York"},
|
|
{"name": "Carol Johnson", "role": "Senior Engineer", "office": "London"},
|
|
{"name": "David Kim", "role": "Product Manager", "office": "San Francisco"},
|
|
{"name": "Eva Mueller", "role": "Engineer", "office": "Berlin"},
|
|
{"name": "Frank Lee", "role": "Data Scientist", "office": "San Francisco"},
|
|
{"name": "Grace Park", "role": "Engineering Manager", "office": "New York"},
|
|
]
|
|
|
|
office_counts = [
|
|
{"office": office, "count": count}
|
|
for office, count in Counter(m["office"] for m in members).items()
|
|
]
|
|
|
|
with PrefabApp() as app:
|
|
with Column(gap=4, css_class="p-6"):
|
|
Heading("Team Directory")
|
|
with Grid(columns=2, gap=4):
|
|
PieChart(
|
|
data=office_counts,
|
|
data_key="count",
|
|
name_key="office",
|
|
)
|
|
DataTable(
|
|
columns=[
|
|
DataTableColumn(key="name", header="Name", sortable=True),
|
|
DataTableColumn(key="role", header="Role", sortable=True),
|
|
DataTableColumn(key="office", header="Office", sortable=True),
|
|
],
|
|
rows=members,
|
|
search=True,
|
|
)
|
|
|
|
return app
|
|
```
|
|
|
|
That `app=True` is doing a lot behind the scenes. It tells FastMCP to set up everything the MCP Apps protocol requires: the renderer resource, the content security policy, the metadata that tells the host "this tool returns a UI." Without it, you'd wire all of that up by hand. With it, you just return Prefab components and FastMCP handles the rest. The host (Claude Desktop, Goose, etc.) loads the result in a sandboxed iframe where the user can sort columns, search, and interact, all client-side with no round-trips to your server.
|
|
|
|
The Prefab code itself reads top-to-bottom like a document. `PrefabApp()` is the root container and everything inside its `with` block becomes the app's UI. `Column` arranges children vertically. `Heading` renders a title. `DataTable` takes rows of data and column definitions, and gives you sorting and search for free. The `with` blocks establish parent-child relationships: nesting components inside each other builds the layout tree.
|
|
|
|
## Running It
|
|
|
|
FastMCP includes a dev server that renders your app tools in a browser, no MCP host needed:
|
|
|
|
```bash
|
|
fastmcp dev apps server.py
|
|
```
|
|
|
|
This opens `http://localhost:8080` where you can pick a tool and see the rendered UI. Try sorting the table columns and typing in the search box.
|
|
|
|
<Frame>
|
|
<img src="/apps/images/dev-app.png" alt="The dev UI showing a rendered Prefab app" />
|
|
</Frame>
|
|
|
|
## Making It Reactive
|
|
|
|
The table above is a static snapshot that renders once from the data your Python code provides. But Prefab apps can also respond to user input in real time, without any server round-trips.
|
|
|
|
The key concept is **state**: a client-side key-value store. Components can read from state (to decide what to display) and write to state (when the user interacts). Because state lives in the browser, updates are instant. See the [Prefab reactivity docs](https://prefab.prefect.io/docs/concepts/expressions) for the full expression language.
|
|
|
|
Here's the same directory with a dropdown filter:
|
|
|
|
```python
|
|
from prefab_ui.app import PrefabApp
|
|
from prefab_ui.components import (
|
|
Column, Heading, Muted, DataTable, DataTableColumn,
|
|
Row, Select, SelectOption, Badge,
|
|
)
|
|
from prefab_ui.components.control_flow import If, Else
|
|
from prefab_ui.rx import Rx
|
|
from fastmcp import FastMCP
|
|
|
|
mcp = FastMCP("My First App")
|
|
|
|
MEMBERS = [
|
|
{"name": "Alice Chen", "role": "Staff Engineer", "office": "San Francisco"},
|
|
{"name": "Bob Martinez", "role": "Lead Designer", "office": "New York"},
|
|
{"name": "Carol Johnson", "role": "Senior Engineer", "office": "London"},
|
|
{"name": "David Kim", "role": "Product Manager", "office": "San Francisco"},
|
|
{"name": "Eva Mueller", "role": "Engineer", "office": "Berlin"},
|
|
]
|
|
|
|
OFFICES = sorted({m["office"] for m in MEMBERS})
|
|
|
|
|
|
@mcp.tool(app=True)
|
|
def team_directory() -> PrefabApp:
|
|
"""Browse the team directory with office filtering."""
|
|
with PrefabApp(state={"office": "all"}) as app:
|
|
with Column(gap=4, css_class="p-6"):
|
|
with Row(gap=2, align="center"):
|
|
Heading("Team Directory")
|
|
Badge(f"{len(MEMBERS)} people", variant="secondary")
|
|
|
|
with Select(name="office", label="Filter by Office"):
|
|
SelectOption("All Offices", value="all")
|
|
for office in OFFICES:
|
|
SelectOption(office, value=office)
|
|
|
|
with If(Rx("office") == "all"):
|
|
DataTable(
|
|
columns=[
|
|
DataTableColumn(key="name", header="Name", sortable=True),
|
|
DataTableColumn(key="role", header="Role", sortable=True),
|
|
DataTableColumn(key="office", header="Office", sortable=True),
|
|
],
|
|
rows=MEMBERS,
|
|
search=True,
|
|
)
|
|
with Else():
|
|
DataTable(
|
|
columns=[
|
|
DataTableColumn(key="name", header="Name", sortable=True),
|
|
DataTableColumn(key="role", header="Role", sortable=True),
|
|
],
|
|
rows=[m for m in MEMBERS if m["office"] == "San Francisco"],
|
|
search=True,
|
|
)
|
|
Muted("Client-side filtering. The full dataset is in the browser.")
|
|
|
|
return app
|
|
```
|
|
|
|
Three new ideas here:
|
|
|
|
**`Rx("office")`** creates a reactive reference to the `office` key in state. It doesn't hold a Python value. It compiles to a browser-side expression that evaluates live as state changes.
|
|
|
|
**`Select(name="office")`** binds the dropdown to the `office` state key. Every time the user picks a new option, `office` updates instantly in the browser.
|
|
|
|
**`If` / `Else`** conditionally renders components based on a reactive expression. When `office` is `"all"`, the full table with an office column shows. Otherwise, the table shows only the matching rows. The switch is instant because it's all client-side.
|
|
|
|
The `state` dict on `PrefabApp` sets initial values when the app loads. Run `fastmcp dev apps server.py` again and try the dropdown.
|
|
|
|
## Next Steps
|
|
|
|
You've built a tool that returns an interactive, reactive UI. This pattern covers a huge range of use cases: build a visualization in Prefab, return it from a tool, and the user gets dashboards, charts, data tables, and status displays right in the conversation.
|
|
|
|
When you need the UI to talk back to your server (forms that save data, buttons that trigger actions, search that queries a database) you promote the tool to a **[FastMCPApp](/apps/interactive-apps)**. That gives you managed backend tools, automatic visibility control, and stable routing so your UI's button clicks reach the right server-side code.
|
|
|
|
- **[Prefab UI](/apps/prefab)** covers the full component library: charts, forms, badges, progress bars, and the [reactive state system](https://prefab.prefect.io/docs/concepts/state) in depth.
|
|
- **[FastMCPApp](/apps/interactive-apps)** is the next step when your UI needs to interact with backend logic.
|
|
- **[App Providers](/apps/providers/approval)** are ready-made capabilities you can add with a single `add_provider()` call.
|