> ## Documentation Index
> Fetch the complete documentation index at: https://prefab.prefect.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# FastMCP

> Build MCP Apps that render inside Claude Desktop, ChatGPT, and other hosts.

Prefab integrates with [FastMCP](https://github.com/PrefectHQ/fastmcp) to build [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) — interactive UIs that render directly inside the conversation. Mark any tool with `app=True` and return a component tree or a `PrefabApp`:

> [!NOTE]
>
> When you install `fastmcp[apps]`, FastMCP pulls in `prefab-ui` with only a minimum version — no upper bound. For production, pin `prefab-ui` explicitly in your own dependencies (e.g. `prefab-ui==0.15.0`). See [Versioning Policy](https://prefab.prefect.io/docs/getting-started/installation.md#versioning-policy) for details.

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from fastmcp import FastMCP
from prefab_ui.app import PrefabApp
from prefab_ui.components import Heading, Text
from prefab_ui.components.control_flow import ForEach
mcp = FastMCP("My Server")

ITEMS = [{"name": "Widget"}, {"name": "Gadget"}, {"name": "Gizmo"}]

@mcp.tool(app=True)
def browse() -> PrefabApp:
    """Show all items."""
    with PrefabApp(state={"items": ITEMS}, css_class="p-6") as app:
        Heading("Items")
        with ForEach("items"):
            Text("{{ name }}")
    return app
```

When a host like Claude Desktop calls this tool, the user sees a fully interactive UI instead of plain text. FastMCP handles the wiring automatically: it registers a shared Prefab renderer as a `ui://` resource, sets the MCP Apps metadata on your tool, and converts `PrefabApp` returns to `structuredContent` in the tool result.

## How It Works

The flow has three steps:

1. **Tool call** — the host calls your tool via MCP
2. **PrefabApp → structuredContent** — FastMCP serializes your return value into the Prefab JSON envelope, including the view, initial state, and any app tools
3. **Renderer** — the host loads the registered Prefab renderer resource and passes it the structured content. The renderer builds the UI.

When the user interacts with the UI (clicks a button, submits a form), [`CallTool`](https://prefab.prefect.io/docs/actions/call-tool) can send a request through MCP back to your server. Its response can contain data or a new component tree; response actions decide how to apply it to the UI. [App-provided tools](https://prefab.prefect.io/docs/mcp/overview.md#app-provided-tools) let the agent invoke an interaction on the open app as well.

## Returning UI

You can return either a `PrefabApp` or a bare component. Returning a component is a shorthand — FastMCP wraps it in a `PrefabApp` automatically.

```python PrefabApp theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.rx import Rx

name = Rx("name")

@mcp.tool(app=True)
def dashboard() -> PrefabApp:
    with Column(gap=4) as view:
        Heading("Dashboard")
        Text(f"Welcome, {name}")
    return PrefabApp(
        title="Dashboard",
        view=view,
        state={"name": "Alice"},
    )
```

```python Bare Component theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@mcp.tool(app=True)
def dashboard() -> Column:
    with Column(gap=4) as view:
        Heading("Dashboard")
        Text("Hello!")
    return view
```

Return a `PrefabApp` when you need initial state, a page title, or reusable definitions. Return a bare component for simple, stateless views.

## Patterns

### Calling Back to the Server

[`CallTool`](https://prefab.prefect.io/docs/actions/call-tool) is the MCP equivalent of [`Fetch`](https://prefab.prefect.io/docs/actions/fetch). It sends a tool call through MCP, and the response is available as `$result` (Python: `RESULT`) in the `on_success` callback:

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.actions import SetState
from prefab_ui.actions.mcp import CallTool
from prefab_ui.rx import RESULT

@mcp.tool(app=True)
def browse() -> PrefabApp:
    with Column(gap=4) as view:
        Input(
            name="q",
            placeholder="Search...",
            on_change=[
                SetState("q", "{{ $event }}"),
                CallTool("search", arguments={"q": "{{ $event }}"}, on_success=SetState("results", RESULT)),
            ],
        )
        Slot("results")
    return PrefabApp(view=view, state={"q": "", "results": None})

@mcp.tool
def search(q: str = "") -> PrefabApp:
    matches = [i for i in ITEMS if q.lower() in i["name"].lower()] if q else ITEMS
    with ForEach("items") as view:
        Text("{{ name }}")
    return PrefabApp(view=view, state={"items": matches})
```

The first tool (`browse`) defines the layout with a `Slot`. The second tool (`search`) returns a component tree that fills that slot. This is the core MCP Apps pattern: the initial tool sets up the shell, and subsequent tool calls swap content in and out.

> [!NOTE]
>
> `search` doesn't need `app=True` — it's a helper tool called from within the UI, not an entry point that a host would show directly. FastMCP still auto-wires it because its return type is `PrefabApp`.

### Dynamic Component Results with Slot

When a `CallTool` writes its result into state via `SetState("key", RESULT)` in `on_success`, a [`Slot`](https://prefab.prefect.io/docs/components/slot) watching that key renders whatever component tree arrives:

```python {5,11} theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
# In the main view
with Slot("detail"):
    Text("Select an item", css_class="text-muted-foreground")

# A tool that returns component content for the slot
@mcp.tool
def get_detail(id: str) -> PrefabApp:
    item = lookup(id)
    with Card() as view:
        CardTitle(item["name"])
        Text(item["description"])
    return PrefabApp(view=view, state={"item": item})
```

The `Slot` shows its fallback children until a `CallTool` populates the state key. This is the same pattern as [Dynamic Component Routes](https://prefab.prefect.io/docs/running/api.md#dynamic-component-routes) in the API Server guide — the server decides what to render, not just what data to return.

### Error Handling

If a tool raises an exception, the MCP protocol surfaces it as an error. Use `on_error` to display it:

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.rx import Rx

new_title = Rx("new_title")

CallTool(
    "add_entry",
    arguments={"title": new_title},
    on_error=ShowToast("{{ $error }}", variant="error"),
)
```

On the server side, just raise:

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@mcp.tool
def add_entry(title: str) -> PrefabApp:
    if not title.strip():
        raise ValueError("Title is required")
    # ...
```

### Tool Visibility

By default, all tools registered on your server are visible to the model — including helper tools meant only for UI interactions. When the model can see tools like `search` or `delete_item`, it may call them directly instead of letting the user interact through the UI.

Use `AppConfig(visibility=["app"])` to mark tools as app-only. These tools remain callable via `CallTool` from the UI, but the host should exclude them when presenting tools to the model:

```python {1,8} theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from fastmcp.apps import AppConfig

@mcp.tool(app=True)
def browse() -> PrefabApp:
    """The entry point — visible to the model."""
    ...

@mcp.tool(app=AppConfig(visibility=["app"]))
def search(q: str = "") -> PrefabApp:
    """Called from the UI only — hidden from the model."""
    ...
```

The entry point tool uses `app=True` so the model can invoke it. Helper tools use `AppConfig(visibility=["app"])` so they're accessible to `CallTool` but won't appear in the model's tool list.

> [!NOTE]
>
> Tool visibility is metadata that the host is responsible for enforcing. The server returns all tools from `tools/list` regardless of visibility — the host filters based on the `visibility` field in the tool's app metadata.

## Host Capabilities

Once your app is running, its [MCP host](https://prefab.prefect.io/docs/mcp/overview.md) connects it to the
conversation. Use [Messages](https://prefab.prefect.io/docs/actions/send-message.md) for user-initiated follow-up
requests and [Model Context](https://prefab.prefect.io/docs/actions/update-context.md) to share the current
selection or other useful state. [App-provided tools](https://prefab.prefect.io/docs/mcp/overview.md#app-provided-tools) let the agent invoke
operations on the open view, and [Display Modes](https://prefab.prefect.io/docs/actions/request-display-mode.md)
let the UI request more space. Availability depends on the host.

## API Server vs FastMCP

Both use the same components and state model. The difference is transport:

| | FastMCP | API Server |
| - | - | - |
| **Transport** | MCP protocol | HTTP (fetch) |
| **Server action** | `CallTool` | `Fetch` |
| **Host actions** | `SendMessage`, `UpdateContext` | — |
| **Hosting** | Inside Claude Desktop, ChatGPT, etc. | Standalone web page |
| **Renderer** | Provided by the MCP host | Bundled in `PrefabApp.html()` |

If you're building an MCP server, use `CallTool`. If you're building a web app, use `Fetch`. `SendMessage` and `UpdateContext` are MCP-only — they communicate with the host's conversation, which doesn't exist in standalone mode. The component tree and client-side actions are identical either way.

## Example App

The [`examples/hitchhikers-guide`](https://github.com/PrefectHQ/prefab/tree/main/examples/hitchhikers-guide) directory contains a complete working MCP server — a Hitchhiker's Guide catalog with search, dialog-based entry creation, inline deletion, and error handling. The same directory also contains a [FastAPI version](https://prefab.prefect.io/docs/running/api.md) of the same app for comparison.

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
uv run examples/hitchhikers-guide/mcp_server.py
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.