FastMCPApp

New in version 3.2.0

Prefab is under active development with frequent breaking changes. FastMCP sets a minimum prefab-ui version but does not pin an upper bound — pin prefab-ui to a specific version in your own dependencies before deploying.

Search a list, fill out a form, click save, the list updates. That pattern — UI that reads and writes data on the server — needs two things: backend tools that actually do the work, and a way to call them from the UI. FastMCPApp handles the wiring. You’ll build up to the contacts app above by the end of this page. Let’s start with something smaller.

A minimal interactive app

The smallest interactive app: a form that saves a note, and a list that updates when the user submits.

from prefab_ui.actions import SetState, ShowToast
from prefab_ui.actions.mcp import CallTool
from prefab_ui.app import PrefabApp
from prefab_ui.components import (
    Badge, Button, Column, ForEach, Form, Heading,
    Input, Row, Separator, Text,
)
from prefab_ui.rx import RESULT
from fastmcp import FastMCP, FastMCPApp

app = FastMCPApp("Notes")
notes_db: list[dict] = []


@app.tool()
def add_note(title: str, body: str) -> list[dict]:
    """Save a note and return all notes."""
    notes_db.append({"title": title, "body": body})
    return list(notes_db)


@app.ui()
def notes_app() -> PrefabApp:
    """Open the notes app."""
    with Column(gap=6, css_class="p-6") as view:
        Heading("Notes")

        with ForEach("notes") as note:
            with Row(gap=2, align="center"):
                Text(note.title, css_class="font-semibold")
                Badge(note.body)

        Separator()

        with Form(
            on_submit=CallTool(
                "add_note",
                on_success=[
                    SetState("notes", RESULT),
                    ShowToast("Note saved!", variant="success"),
                ],
                on_error=ShowToast("Failed to save", variant="error"),
            )
        ):
            Input(name="title", label="Title", required=True)
            Input(name="body", label="Body", required=True)
            Button("Add Note")

    return PrefabApp(view=view, state={"notes": list(notes_db)})


mcp = FastMCP("Notes Server", providers=[app])

With a host that honors app visibility, the model sees one tool: notes_app. Calling it opens the UI. When the user submits the form, CallTool("add_note") fires, the server saves the note, returns the updated list, and SetState("notes", RESULT) writes that list back into state. ForEach("notes") re-renders. add_note is omitted from the model’s tool list.

Why not just `@mcp.tool(app=True)`?

A fair question. Any Interactive Tool can call a server tool — there’s nothing stopping you from putting CallTool("add_note") inside a regular @mcp.tool(app=True). It works for one or two tools. Things get harder once the app grows:

Which tools should the model see, and which are UI-only?
What happens to CallTool("add_note") when you mount this server under a namespace and the tool becomes notes_add_note?
How do you keep it all wired correctly as you compose servers?

FastMCPApp owns these concerns. Entry points register as model-visible, backend tools register as UI-only, and hosts act on those declarations to decide what the model sees. App tool visibility is not a security boundary. Backend tools remain callable through direct MCP requests by clients that know their names, subject to the server’s authentication and authorization checks. Use authorization and server-side validation to enforce access and approval requirements; visibility metadata only declares the intended audience. Composition is handled at serialization. Inside a FastMCPApp, FastMCP resolves every CallTool reference, by name or by function, to whatever that tool is actually called when the UI reaches the host. Mount the server under a namespace and the button calls notes_add_note; put a gateway in front and it calls whatever the gateway lists. Renaming cannot break it. The architecture page covers how that resolution works. The one rule that comes with this: an app name must be unique within a server. Composing the same app twice breaks its UI — two copies of FastMCPApp("notes") are indistinguishable no matter what namespaces you mount them under, so FastMCP declines to bind rather than picking one. Name apps for what they serve: FastMCPApp("notes-acme") and FastMCPApp("notes-globex"). The architecture page explains why identity works this way. The rest of this page covers each piece in turn.

`@app.ui()` — entry points

Entry points are what the model sees. They return a PrefabApp and default to visibility=["model"], asking hosts to include them in the LLM tool list and reject calls to them from the UI.

@app.ui()
def dashboard() -> PrefabApp:
    """The model calls this to open the dashboard."""
    with Column(gap=4, css_class="p-6") as view:
        Heading("Dashboard")
        ...
    return PrefabApp(view=view)

@app.ui() accepts name, description, title, tags, icons, annotations, auth, and timeout.

`@app.tool()` — backend tools

Backend tools do the work. By default they declare visibility=["app"], asking hosts to expose them to the UI and omit them from the model’s tool list.

@app.tool()
def save_contact(name: str, email: str) -> list[dict]:
    """Save a contact and return the updated list."""
    db.append({"name": name, "email": email})
    return list(db)

If you want a tool callable by both the model and the UI, pass model=True:

@app.tool(model=True)
def list_contacts() -> list[dict]:
    """Both the model and the UI can call this."""
    return list(db)

Backend tools support name, description, auth, and timeout. App tool names matching __<12 lowercase hex>_<name> (for example, __abcdef012345_save) are reserved for generated tool addresses. @app.tool(), @app.ui(), and app.add_tool() reject that pattern with a ValueError at registration. Other names containing double underscores, such as __save or save__contact, are allowed.

`CallTool` — UI → backend

CallTool is how the UI invokes a backend tool. Pass the tool’s name or the function itself; inside a FastMCPApp, both resolve to the tool’s current address when the UI is serialized:

from prefab_ui.actions.mcp import CallTool

CallTool("save_contact", arguments={"name": "Alice", "email": "alice@example.com"})

# Or pass the function itself
CallTool(save_contact, arguments={...})

Arguments can reference state with Rx:

from prefab_ui.rx import STATE

CallTool("search", arguments={"query": STATE.search_term})

Handling results

Server calls are async. Use on_success and on_error callbacks:

from prefab_ui.actions import SetState, ShowToast
from prefab_ui.rx import RESULT

CallTool(
    "save_contact",
    on_success=[
        SetState("contacts", RESULT),
        ShowToast("Saved!", variant="success"),
    ],
    on_error=ShowToast("Something went wrong", variant="error"),
)

RESULT is a reactive reference to the tool’s return value, available inside on_success. ERROR (from prefab_ui.rx) is the counterpart inside on_error. Callbacks can be a single action or a list; they execute in order and short-circuit on error.

`result_key` shorthand

When a tool’s return value should replace a state key, use result_key:

CallTool("list_contacts", result_key="contacts")

# same as:
CallTool("list_contacts", on_success=SetState("contacts", RESULT))

Actions

CallTool is one of several actions. Actions attach to handlers like on_click, on_submit, and on_change. Client-side actions run instantly in the browser, no server round-trip:

from prefab_ui.actions import SetState, ToggleState, AppendState, PopState, ShowToast

SetState("count", 42)
ToggleState("expanded")
AppendState("items", {"name": "New Item"})
PopState("items", 0)
ShowToast("Done!", variant="success")

Pass a list to chain actions:

Button(
    "Reset",
    on_click=[
        SetState("query", ""),
        SetState("results", []),
        ShowToast("Cleared"),
    ],
)

Loading states

A common pattern: disable a button and show a spinner while a call is in flight.

from prefab_ui.rx import Rx

saving = Rx("saving")

Button(
    saving.then("Saving...", "Save"),
    disabled=saving,
    on_click=[
        SetState("saving", True),
        CallTool(
            "save_data",
            on_success=[
                SetState("saving", False),
                SetState("result", RESULT),
                ShowToast("Saved!", variant="success"),
            ],
            on_error=[
                SetState("saving", False),
                ShowToast("Failed", variant="error"),
            ],
        ),
    ],
)

# PrefabApp(view=view, state={"saving": False, ...})

Forms

Forms collect input and submit it to a tool. When submitted, named input values become the tool’s arguments.

Manual forms

from prefab_ui.components import Form, Input, Select, SelectOption, Textarea, Button

with Form(
    on_submit=CallTool(
        "create_ticket",
        on_success=ShowToast("Ticket created!", variant="success"),
    )
):
    Input(name="title", label="Title", required=True)
    with Select(name="priority", label="Priority"):
        SelectOption("Low", value="low")
        SelectOption("Medium", value="medium")
        SelectOption("High", value="high")
    Textarea(name="description", label="Description")
    Button("Create Ticket")

On submit, CallTool receives {"title": ..., "priority": ..., "description": ...}.

Forms from Pydantic models

For structured input, Form.from_model() generates the whole form — inputs, labels, validation:

from typing import Literal
from pydantic import BaseModel, Field

class BugReport(BaseModel):
    title: str = Field(title="Bug Title")
    severity: Literal["low", "medium", "high", "critical"] = Field(
        title="Severity", default="medium"
    )
    description: str = Field(title="Description")


@app.ui()
def report_bug() -> PrefabApp:
    with Column(gap=4, css_class="p-6") as view:
        Heading("Report a Bug")
        Form.from_model(
            BugReport,
            on_submit=CallTool(
                "create_bug",
                on_success=ShowToast("Bug filed!", variant="success"),
            ),
        )
    return PrefabApp(view=view)


@app.tool()
def create_bug(data: BugReport) -> str:
    return f"Created: {data.title}"

str becomes a text input, Literal becomes a select, bool becomes a checkbox. Field titles and defaults are respected.

Composition and namespacing

The reason FastMCPApp exists — and why you’d pick it over a plain @mcp.tool(app=True) that calls other tools — is composition safety. When you mount a server under a namespace, tool names get prefixed:

platform = FastMCP("Platform")
platform.mount(contacts_server, namespace="contacts")

# "save_contact" becomes "contacts_save_contact"

In a plain @mcp.tool(app=True), CallTool("save_contact") would now point at a tool that no longer exists. Inside a FastMCPApp, the same call is addressed by the app’s identity and rewritten to contacts_save_contact on the way out, so the app works the same whether standalone or mounted.

Mounting

FastMCPApp is a Provider. Add it to a server with providers= or add_provider:

mcp = FastMCP("Platform", providers=[app])

# or
mcp = FastMCP("Platform")
mcp.add_provider(app)

Multiple apps can coexist; each gets its own global keys, so there’s no collision even if two apps have a tool named save.

mcp = FastMCP("Platform", providers=[contacts_app, inventory_app, billing_app])

Running standalone

For development, FastMCPApp has a run() shortcut that wraps itself in a temporary FastMCP server:

app = FastMCPApp("Contacts")
# ... register tools ...

if __name__ == "__main__":
    app.run()

A full example: contact manager

This brings everything together — entry point, backend tools, Pydantic form, manual form, state, actions, and multi-visibility.

from __future__ import annotations

from typing import Literal

from prefab_ui.actions import SetState, ShowToast
from prefab_ui.actions.mcp import CallTool
from prefab_ui.app import PrefabApp
from prefab_ui.components import (
    Badge, Button, Column, ForEach, Form,
    Heading, Input, Muted, Row, Separator, Text,
)
from prefab_ui.rx import RESULT, Rx
from pydantic import BaseModel, Field
from fastmcp import FastMCP, FastMCPApp

contacts_db: list[dict] = [
    {"name": "Arthur Dent", "email": "arthur@earth.com", "category": "Customer"},
    {"name": "Ford Prefect", "email": "ford@betelgeuse.org", "category": "Partner"},
]


class ContactModel(BaseModel):
    name: str = Field(title="Full Name", min_length=1)
    email: str = Field(title="Email")
    category: Literal["Customer", "Vendor", "Partner", "Other"] = "Other"


app = FastMCPApp("Contacts")


@app.tool()
def save_contact(data: ContactModel) -> list[dict]:
    """Save a new contact and return the updated list."""
    contacts_db.append(data.model_dump())
    return list(contacts_db)


@app.tool()
def search_contacts(query: str) -> list[dict]:
    """Filter contacts by name or email."""
    q = query.lower()
    return [
        c for c in contacts_db
        if q in c["name"].lower() or q in c["email"].lower()
    ]


@app.tool(model=True)
def list_contacts() -> list[dict]:
    """Return all contacts. Visible to both the model and the UI."""
    return list(contacts_db)


@app.ui()
def contact_manager() -> PrefabApp:
    """Open the contact manager."""
    with Column(gap=6, css_class="p-6") as view:
        Heading("Contacts")

        with ForEach("contacts") as contact:
            with Row(gap=2, align="center"):
                Text(contact.name, css_class="font-medium")
                Muted(contact.email)
                Badge(contact.category)

        Separator()

        Heading("Add Contact", level=3)
        Form.from_model(
            ContactModel,
            on_submit=CallTool(
                "save_contact",
                on_success=[
                    SetState("contacts", RESULT),
                    ShowToast("Contact saved!", variant="success"),
                ],
                on_error=ShowToast("Failed to save", variant="error"),
            ),
        )

        Separator()

        Heading("Search", level=3)
        with Form(
            on_submit=CallTool(
                "search_contacts",
                arguments={"query": Rx("query")},
                on_success=SetState("contacts", RESULT),
            )
        ):
            Input(name="query", placeholder="Search by name or email...")
            Button("Search")

    return PrefabApp(view=view, state={"contacts": list(contacts_db)})


mcp = FastMCP("Contacts Server", providers=[app])

if __name__ == "__main__":
    mcp.run()

Also available as a runnable server at examples/apps/contacts/contacts_server.py.

Next steps

Interactive Tools — the building blocks: charts, tables, dashboards, reactive state
Examples — complete working servers
Development — preview and test app tools locally
Prefab UI docs — full component reference

Get Started

Servers

Apps

Clients

Integrations

More

A minimal interactive app

Why not just `@mcp.tool(app=True)`?

`@app.ui()` — entry points

`@app.tool()` — backend tools

`CallTool` — UI → backend

Handling results

`result_key` shorthand

Actions

Loading states

Forms

Manual forms

Forms from Pydantic models

Composition and namespacing

Mounting

Running standalone

A full example: contact manager

Next steps

A minimal interactive app

Why not just @mcp.tool(app=True)?

@app.ui() — entry points

@app.tool() — backend tools

CallTool — UI → backend

Handling results

result_key shorthand

Actions

Loading states

Forms

Manual forms

Forms from Pydantic models

Composition and namespacing

Mounting

Running standalone

A full example: contact manager

Next steps

Why not just `@mcp.tool(app=True)`?

`@app.ui()` — entry points

`@app.tool()` — backend tools

`CallTool` — UI → backend

`result_key` shorthand