Widget components

@Tool({ ..., ui: { template: { file: join(__dirname, "weather.widget.tsx") }, resourceMode?: "cdn" | "inline" } })

// weather.widget.tsx
export default function WeatherWidget({ output, input, loading }) { … }

import { useStructuredContent, useToolOutput, useToolInput, useCallTool, … } from "@frontmcp/ui/react";
import { Card, Badge, Button, Table, … } from "@frontmcp/ui/components";
import { FrontMcpThemeProvider } from "@frontmcp/ui/theme";
import { html, trustedHtml, renderToolTemplate } from "@frontmcp/uipack";

Reference

The Playground can't import @frontmcp/ui or @frontmcp/uipack, or bundle a widget file, so only one example on this page runs in it. Every other example was run for real with FrontMCP 1.9.2, React 19 and MUI 7: widgets bundled by a server in Node, in a CommonJS project and in an ES module one, and rendered in Chromium. With 1.9.3, widgets that read the call and call tools with the hooks below were bundled and rendered again, in both kinds of project; the MUI components weren't. The hooks and components were also rendered in jsdom and with React's server renderer on 1.8.7; @frontmcp/ui 1.9.2 is the same code.

Building a widget file

Install @frontmcp/ui in the server's project, even for a widget that doesn't import it: the code FrontMCP adds to mount your component imports McpBridgeProvider from @frontmcp/ui/react. npm 7 and later install its peers, react, react-dom, @mui/material, @emotion/react and @emotion/styled, along with it.

npm install @frontmcp/ui

Point ui.template at the file with an absolute path, and export the component as the default:

import { join } from "node:path";
import { Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({
  name: "get_weather",
  description: "Current weather for a city",
  inputSchema: { city: z.string() },
  outputSchema: { city: z.string(), tempC: z.number(), conditions: z.string() },
  ui: { template: { file: join(__dirname, "weather.widget.tsx") } },
})
export class GetWeather extends ToolContext {
  async execute({ city }: { city: string }) {
    return { city, tempC: 21, conditions: "Sunny" };
  }
}

type Weather = { city: string; tempC: number; conditions: string };

export default function WeatherWidget({ output }: { output: Weather | null }) {
  if (!output?.city) return <p>Loading…</p>;
  return (
    <div className="weather">
      <h2>{output.city}</h2>
      <p>{output.tempC}°C, {output.conditions}</p>
    </div>
  );
}

In Chromium the page shows Oslo, 21°C, Sunny, opened on its own and in an MCP Apps host. It checks for the field it needs, output?.city, and not for output: a failed result's error text is truthy too (The props). See more examples below.

The server can be CommonJS, which is what frontmcp create makes, or an ES module ("type": "module"), where the path is join(import.meta.dirname, "weather.widget.tsx"). Changed in 1.9: an ES module server couldn't bundle widget files. Every call logged applyUI: UI rendering failed with Dynamic require of "path" is not supported, and the result had no page.

• A relative file is resolved from the working directory, not from the tool's file: use join(__dirname, …), or import.meta.dirname in an ES module. With a plain tsc build, __dirname is a folder under dist/, so copy the widget files there too. Otherwise every call logs applyUI: UI rendering failed with FileSource widget not found (ENOENT): no file at "…", and when the same path exists under src/, the message names that file.
• frontmcp build copies the *.widget.tsx and *.widget.jsx files into its output, next to the bundle for --target node, and prints copied 1 widget source file (*.widget.tsx/jsx) to dist/node. The install-<name>.sh script it writes copies the bundle, the manifest and the runner only, so an installed build has no widgets, and the staging folder of --target mcpb has none either. Other local files a widget imports aren't copied: a widget with import { greet } from "./format" fails in the built server with Failed to bundle FileSource "…/dist/node/hello.widget.tsx" and Could not resolve "./format", so keep a widget in one file.
• FrontMCP bundles the file with esbuild, which @frontmcp/uipack lists as an optional peer dependency, so nothing installs it for you. A project from frontmcp create has it, through the frontmcp package; anywhere else, install it as a dependency, not a dev dependency, since it's loaded when the tool is called. Without it every call logs applyUI: UI rendering failed with FileSource widget "…" needs esbuild, which is not installed.
• The file is bundled when the tool is called, or at startup for a static tool. Imports come from the server's node_modules. A page with MUI in it is about 460 KB.
• Name the file *.widget.tsx and leave it out of the server's own tsc build, which would otherwise need "jsx" settings and React's types.

The props

FrontMCP renders your default export inside McpBridgeProvider, with three props:

Check for the fields you need rather than for output itself: a failed result's error text is truthy.

Changed in 1.8.7: after an MCP Apps host's result, output used to be the result's content array, [{ type: "text", text: "{…}" }], and widgets read useStructuredContent() first to get the object. It's the object now, and useStructuredContent() still returns it.

Changed in 1.9: a static page used to start with output and input set to {} and loading false, so a widget that checked if (!output) drew the empty object. With the OpenAI Apps SDK, output stayed {} until the host assigned a new toolOutput.

resourceMode: "cdn" or "inline"

Where esm.sh can't be reached, a "cdn" page stays on "Loading widget...". Set resourceMode: "inline" for hosts that block outside scripts, and for static widgets meant for them.

Hooks

@frontmcp/ui/react (also exported from @frontmcp/ui) reads the call and talks to the host through the page's bridge. A widget file is already inside McpBridgeProvider.

McpBridgeProvider takes config, onReady and onError. In a FrontMCP page it uses the page's window.FrontMcpBridge, and ready is true from the first render, before an MCP Apps host has answered the handshake. Outside a provider the hooks return empty values, and call() fails with Bridge not initialized.

The widget renders before an MCP Apps host answers ui/initialize, so its first render has useCapability("canCallTools") false, useTheme() "light" and useHostContext() as the page's own defaults. The answer makes the hooks render again, so a button that waits for useCapability("canCallTools") appears once the host can call tools, and stays hidden in a host that never answers. useSendMessage() and useOpenLink() don't wait: they ask the host, and error has its refusal, like ui/message isn't supported (code: -32601).

Changed in 1.8.7: useCapability() stayed false and useHostContext() stayed null for good in an MCP Apps host, so a button behind useCapability("canCallTools") never showed, and widgets read bridge.getHostContext() themselves.

Changed in 1.8.6: useTheme() used to stay "light" when the handshake said "dark" until the host sent a change. The handshake's hostContext now reaches the bridge's onContextChange listeners, so it's the theme the host answered, and the bridge also sets the page's color-scheme from it (Hosts and platforms).

A tool that fails in the host usually comes back as a result with isError: true, in data, not in error. error is for calls that couldn't be made, like Tool calls not supported on this platform (ext-apps) when the host didn't answer the handshake.

Components

@frontmcp/ui/components, and one entry point per component (@frontmcp/ui/components/Card), are React components built on MUI. Put them inside FrontMcpThemeProvider.

LoaderProvider custom={({ variant, label, value }) => …} replaces every Loader under it with your own; useLoaderContext() reads it.

These are React components. The HTML-string functions the upstream guides show, like card(), badge() and descriptionList() from @frontmcp/ui, don't exist in 1.9.3 (Troubleshooting).

Theme

@frontmcp/ui/theme:

Renderers

@frontmcp/ui/renderer shows content of a detected kind. detectContentType(value) guesses the kind:

registerAllRenderers() registers the renderers, which renderContent(value, options?) needs: pdf, chart, flow, map, mermaid, math, image, video, audio, csv, jsx, mdx and html, in that order of priority. The chart, map, PDF and diagram libraries are optional peers of @frontmcp/ui, not installed with it. Each renderer is also its own entry point, like @frontmcp/ui/renderer/csv.

@frontmcp/uipack

The package FrontMCP builds pages with, installed with @frontmcp/sdk. Its root works from CommonJS and from ES modules.

Other entry points

• @frontmcp/ui/bridge: the bridge as a class, FrontMcpBridge, with its adapters and generateBridgeIIFE(), for pages FrontMCP doesn't build.
• @frontmcp/ui/runtime: detectContentType, and transpileJsx() with the Babel loader it uses.
• @frontmcp/ui/auth: components for the sign-in pages, on Custom login UI.

Usage

Using the components in a widget

card.widget.tsx puts the result in a Card with a Badge, inside the theme. The tool is the one above, with this file as template.

import { Badge, Card } from "@frontmcp/ui/components";
import { FrontMcpThemeProvider } from "@frontmcp/ui/theme";

type Weather = { city: string; tempC: number; conditions: string };

export default function WeatherCard({ output }: { output: Weather | null }) {
  if (!output?.city) return null;
  return (
    <FrontMcpThemeProvider>
      <Card title={output.city} subtitle="Current weather">
        <p>{output.tempC}°C</p>
        <Badge label={output.conditions} variant="success" />
      </Card>
    </FrontMcpThemeProvider>
  );
}

The page, about 460 KB with resourceMode: "cdn" and 1.1 MB with "inline", shows Oslo, Current weather, 21°C and a Sunny chip in Chromium, with "inline" even with esm.sh blocked.

Calling a tool from a React widget

The button calls get_weather through the host, and data is the host's whole result. Until a call has answered, the widget shows output.

import { useCallTool } from "@frontmcp/ui/react";

type Weather = { city: string; tempC: number };

export default function Refreshable({ output }: { output: Weather | null }) {
  const [refresh, { data, loading, error }] = useCallTool<{ city: string }, Weather>("get_weather");

  const weather = data?.structuredContent ?? (output?.city ? output : null);
  return (
    <div>
      <p>{weather ? `${weather.city}: ${weather.tempC}°C` : "No data yet"}</p>
      <button disabled={loading} onClick={() => refresh({ city: "Bergen" })}>Bergen</button>
      {error && <p role="alert">{error.message}</p>}
      {data?.isError && <p role="alert">The tool failed.</p>}
    </div>
  );
}

In an MCP Apps host, the paragraph shows Oslo: 21°C, from the embedded output or the host's result, and clicking sends tools/call for get_weather to the host, which calls the server as itself (Calling a tool from a widget); the paragraph then shows Bergen: 12°C. In a frame whose parent doesn't answer, clicking shows Tool calls not supported on this platform (ext-apps). Both were run in Chromium.

Splitting a template into functions

Template functions don't need React. html from @frontmcp/uipack builds the same trusted markup as ctx.helpers.html, so pieces of a widget can live in their own file and be tested on their own:

import { html } from "@frontmcp/uipack";

export const badge = (text: string) => html`<span class="badge">${text}</span>`;

export const forecast = (days: { day: string; tempC: number }[]) =>
  html`<ul>${days.map((d) => html`<li>${d.day}: ${d.tempC}°C ${d.tempC > 20 ? badge("warm") : null}</li>`)}</ul>`;

import { Tool, ToolContext, z, type TemplateContext } from "@frontmcp/sdk";
import { forecast } from "./weather-parts";

type Forecast = { city: string; days: { day: string; tempC: number }[] };

@Tool({
  name: "get_forecast",
  description: "Three-day forecast",
  inputSchema: { city: z.string() },
  ui: { template: (ctx: TemplateContext<{ city: string }, Forecast>) => ctx.helpers.html`<h2>${ctx.output.city}</h2>${forecast(ctx.output.days)}` },
})
export class GetForecast extends ToolContext {
  async execute({ city }: { city: string }): Promise<Forecast> {
    return { city, days: [{ day: "Mon", tempC: 19 }, { day: "Tue", tempC: 23 }] };
  }
}

The page's body is <h2>Oslo</h2><ul><li>Mon: 19°C </li><li>Tue: 23°C <span class="badge">warm</span></li></ul>: markup from @frontmcp/uipack's html is trusted by ctx.helpers.html, so it isn't escaped twice.

Without @frontmcp/uipack in your imports, pass ctx.helpers to the pieces instead. The Playground can run this one:

import type { TemplateContext } from "@frontmcp/sdk";

type Helpers = TemplateContext["helpers"];

export const badge = (h: Helpers, text: string) => h.html`<span class="badge">${text}</span>`;

export const forecast = (h: Helpers, days: { day: string; tempC: number }[]) =>
  h.html`<ul>${days.map((d) => h.html`<li>${d.day}: ${d.tempC}°C ${d.tempC > 20 ? badge(h, "warm") : null}</li>`)}</ul>`;

Testing a template without a server

renderToolTemplate() renders a template as a call would, so a unit test can check the markup:

import { test } from "node:test";
import assert from "node:assert/strict";
import { renderToolTemplate } from "@frontmcp/uipack";
import { forecast } from "./weather-parts";

test("warm days get a badge", () => {
  const { html, uiType, meta } = renderToolTemplate({
    toolName: "get_forecast",
    input: { city: "Oslo" },
    output: { city: "Oslo", days: [{ day: "Tue", tempC: 23 }] },
    template: (ctx: any) => ctx.helpers.html`${forecast(ctx.output.days)}`,
  });
  assert.equal(uiType, "html");
  assert.equal(meta["ui/mimeType"], "text/html;profile=mcp-app");
  assert.match(html, /<li>Tue: 23°C <span class="badge">warm<\/span><\/li>/);
});

Troubleshooting

Dynamic require of "path" is not supported

Logged with applyUI: UI rendering failed for a .tsx template in the Playground, which runs FrontMCP in the browser. Widget files are bundled from the file system, by a server on Node. Before 1.9, an ES module server on Node failed with the same message (Building a widget file); since 1.9 it bundles them.

FileSource widget "…" needs esbuild, which is not installed

Logged with applyUI: UI rendering failed, and the result has no page. FrontMCP loads esbuild when the tool is called, and it's an optional peer of @frontmcp/uipack, so npm install esbuild in the server's project, as a dependency and not a dev dependency.

FileSource widget not found (ENOENT): no file at "…"

The widget file isn't where the compiled tool looks: join(__dirname, …) points into the build output, where tsc doesn't copy *.widget.tsx files. The message says so, and names the file under src/ when the same path exists there. Copy the widgets next to the output, or build with frontmcp build.

FileSource widget "…" requires the @frontmcp/ui package

The full message goes on: which provides the React bridge mount that's injected at bundle time. Install it (e.g. npm install @frontmcp/ui or yarn add @frontmcp/ui) and try again. Install @frontmcp/ui in the server's project.

Module '"@frontmcp/ui"' has no exported member 'card'

Or, at runtime, The requested module '@frontmcp/ui' does not provide an export named 'card'. @frontmcp/ui 1.9.3 has no HTML-string components: card, badge, button, descriptionList, form and input are gone. Use the React components in a widget file, or write the markup with html.

My widget renders with empty data

• It checks if (!output), which passes for the error text of a failed result, so the widget draws it. Check for a field, like output?.city.
• It reads a field that outputSchema doesn't declare, which FrontMCP removed from the result (Fields the schema doesn't declare).

The page stays on "Loading widget..."

React didn't load from esm.sh. Set resourceMode: "inline" (resourceMode).

Bridge not initialized

A hook's call() ran outside McpBridgeProvider: in a component rendered outside the widget file's tree, or in a test. Wrap it in McpBridgeProvider.