docs/apps/architecture.mdx
import { VersionBadge } from '/snippets/version-badge.mdx'
<VersionBadge version="3.2.0" />You don't need this page to build apps. It's for when something isn't rendering the way you expect, when UI tool calls aren't reaching your server, or when you're writing custom HTML apps and need to understand the protocol directly.
An MCP app moves through five stages from Python to pixels:
Python components → JSON tree → structuredContent → Renderer iframe → Host UI
You write Prefab components. FastMCP serializes them to a JSON component tree and delivers it as structuredContent on the tool result. The host loads the Prefab renderer in a sandboxed iframe, pushes the JSON in, and the renderer paints the UI. If the UI calls server tools, it talks back through the same postMessage channel.
The sections below walk each stage.
When you mark a tool with app=True or @app.ui(), FastMCP wires up the metadata and renderer resource that the protocol requires.
app=True flagapp on @mcp.tool accepts True, an AppConfig, or a dict. When you pass True, FastMCP explicitly marks the tool as a Prefab UI tool and stamps placeholder UI metadata so the provider can synthesize the correct renderer resource later. When you omit app, FastMCP only applies this automatically if the tool's return type is a Prefab type (PrefabApp, Component, or unions containing them).
The tool and renderer are linked through a resourceUri field in the metadata. Internally, registration uses the placeholder URI ui://prefab/renderer.html; when tools and resources are listed or read, FastMCP rewrites that placeholder to a per-tool URI like ui://prefab/tool/<hash>/renderer.html and synthesizes the matching renderer resource on demand.
FastMCPApp uses the same mechanism but adds two things. First, it tags every tool — both @app.ui() entry points and @app.tool() backends — with meta["fastmcp"]["app"] set to the app's name. That tag lets the server identify which app a tool belongs to when routing UI calls.
Second, it sets meta["ui"]["visibility"] to control who can see each tool. Entry points default to ["model"] (LLM-visible). Backend tools default to ["app"] (UI-only). Hosts use this to filter the tool list.
When a Prefab tool runs, its return value — a PrefabApp or a bare Component — becomes a JSON blob the renderer can interpret.
PrefabApp.to_json()The entry point is PrefabApp.to_json(). It walks the component tree and produces a JSON object with three top-level keys: view (the component tree), state (initial state values), and _meta (routing metadata).
FastMCP passes a tool_resolver callback to to_json(). Whenever the tree contains a CallTool action that references a function (not a string), the resolver converts it to a ResolvedTool with the function's registered name. For FastMCPApp backend tools, that registered name is then wrapped in the deterministic hashed format described below. The resolver also handles unwrap_result — a flag telling the renderer to unwrap single-value results from the {"result": value} envelope FastMCP uses for schema compliance.
FastMCP still tags app tools with meta["fastmcp"]["app"], but backend routing no longer depends on sending the app name through each tool call. During serialization, FastMCP passes a resolver to PrefabApp.to_json(). When the tree contains CallTool(save_contact), the resolver turns it into a deterministic hashed name such as <hash>_save_contact, where the hash is derived from the app name and backend tool name.
That hashed name rides along inside structuredContent all the way to the renderer. When the renderer calls the backend tool, it sends the hashed tool name in the normal MCP tools/call request. The server recognizes that format and routes through the app-tool lookup path described below.
The final tool result has two parts: content (a list of TextContent blocks for the LLM) and structuredContent (the JSON tree for the renderer). By default, Prefab tools send "[Rendered Prefab UI]" as the text content — just enough for the LLM to know something was rendered. If you return a ToolResult explicitly, you control both halves.
Normal tool calls go through the provider chain, which applies transforms (namespace prefixes, visibility filters) before resolving by name. App UI calls need a different path.
Backend tools are typically hidden from the model (visibility=["app"]). Visibility transforms would filter them out of normal resolution. And namespace transforms might rename them — save_contact becomes contacts_save_contact — while the renderer needs a stable way to call the original backend.
Hashed lookup solves both problems. FastMCP first tries normal tool resolution. If no visible tool matches and the requested name looks like <hash>_<local_name>, FastMCP calls get_tool_by_hash(hash, local_name). That lookup walks the provider tree directly, skipping transforms. It finds an app-visible tool by its original registered name and verifies that its stored meta["fastmcp"]["_tool_hash"] matches the requested hash.
That's why CallTool(save_contact) keeps working when the server is mounted under a namespace. The renderer sends a deterministic hashed backend name; the server uses get_tool_by_hash to find the original tool without transforms in the way.
Authorization still applies. The hashed bypass skips name and visibility transforms, but auth checks still run against the tool's auth config before execution.
get_tool_by_hash is defined on the Provider base class and overridden by aggregate and wrapped providers. Aggregate providers fan out the lookup across child providers in parallel. Wrapped providers (like FastMCPProvider, which wraps a nested FastMCP server) delegate to the inner server's hashed lookup. Backend tools are reachable through any depth of composition.
The Prefab renderer is a self-contained JavaScript application that interprets the JSON component tree and renders it as a React UI.
FastMCP exposes the renderer through per-tool resources such as ui://prefab/tool/<hash>/renderer.html, each with MIME type text/html;profile=mcp-app. The HTML is bundled inside the prefab-ui Python package; get_renderer_html() returns it as a string. The resources are synthesized on demand from each tool's UI metadata, so CSP and permissions can differ per tool even though they use the same Prefab renderer.
The resource also carries CSP metadata (via get_renderer_csp()) declaring the CDN domains the renderer needs. Hosts use this to configure the iframe's Content Security Policy.
postMessage communicationThe renderer lives in a sandboxed iframe and communicates with the host using postMessage. The protocol follows the MCP Apps extension spec:
The host pushes the tool result (with structuredContent) into the iframe. The renderer parses the component tree, initializes state, and renders the UI. When the user interacts — submitting a form, clicking a button — and the interaction triggers a CallTool action, the renderer sends a callServerTool message back to the host via postMessage. The host forwards it as a regular MCP tools/call request to the server, using the hashed backend name that FastMCP serialized into the action.
The response flows back the same way: server → host → iframe via postMessage, and the renderer updates state with the result.
The @modelcontextprotocol/ext-apps JavaScript SDK provides the App class (sometimes called AppBridge) that manages the postMessage handshake. It handles connection negotiation, tool result delivery, server tool calls, and host context (safe area insets, theme preferences). The Prefab renderer uses it internally; you only touch it directly when building custom HTML apps.
fastmcp dev apps simulates the host-side behavior locally without a real MCP client.
Two HTTP servers. Your MCP server runs on port 8000 with the Streamable HTTP transport. The dev UI runs on port 8080 and serves a picker page that lists your app tools.
A reverse proxy at /mcp on the dev server forwards requests to your MCP server. This matters because the renderer iframe runs on localhost:8080 and your MCP server runs on localhost:8000 — without the proxy, the renderer's callServerTool requests would be cross-origin and the browser would block them. The proxy keeps everything same-origin from the iframe's perspective.
When you select a tool and click launch, the dev UI calls the tool through the proxy, receives the structuredContent response, and opens a new tab. That tab loads the tool's renderer resource (via the proxy), creates an AppBridge, and pushes the tool result into the renderer. From here on it matches what a real host provides: the renderer displays the UI, and any CallTool actions route back through the proxy to your server.
Auto-reload is on by default, so changes to your server code restart the MCP server automatically. The dev UI keeps running — relaunch the tool to see changes.