Tools with a UI

Your first widget

ui.template is a function FrontMCP calls after every call, with the call's input and output. What it returns, built with ctx.helpers.html so every value is escaped, becomes the page. The result's content and structuredContent don't change, and the page travels next to them, in _meta["ui/html"]. The Playground's Widget tab shows the page as an MCP Apps host would. Press Close ticket:

import { PublicMcpError, Tool, ToolContext, z, type TemplateContext } from "@frontmcp/sdk";
import { tickets, type Ticket } from "./tickets";

@Tool({
  name: "get_ticket",
  description: "Get one support ticket by its id, with its status and customer.",
  inputSchema: { id: z.string().describe("Ticket id, like T-1") },
  ui: {
    template: (ctx: TemplateContext<{ id: string }, Ticket>) => ctx.helpers.html`
      <article style="padding: 12px 16px; border-radius: 8px; background: #f6f7f9; color: #23272f; font: 15px system-ui">
        <p>${ctx.output.id} · ${ctx.output.customer}</p>
        <h2>${ctx.output.title}</h2>
        <p>Status: <span id="status">${ctx.output.status}</span></p>
        <button data-tool-call="close_ticket" data-tool-args="${JSON.stringify({ id: ctx.output.id })}">Close ticket</button>
      </article>
      <script>
        document.addEventListener("tool:success", (event) => {
          const result = event.detail.result;
          document.getElementById("status").textContent = result.isError ? result.content[0].text : result.structuredContent.status;
        });
      </script>`,
  },
})
export class GetTicket extends ToolContext {
  async execute({ id }: { id: string }) {
    const ticket = tickets.find((t) => t.id === id);
    if (!ticket) this.fail(new PublicMcpError(`There's no ticket ${id}.`));
    return ticket;
  }
}

The button's click goes from the page's bridge script to the host, and from the host to your server as an ordinary tools/call: the Wire tab has it, tagged widget.

Choosing how a widget is served

By default a widget is served inline: every result carries the whole page, about 38 KB, rendered with that call's data. A static widget is rendered once, when the server starts, and served as the resource ui://widget/<tool>.html. The host reads it once, then hands the page each result, which the page draws itself:

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

type Queue = { tickets: { id: string; title: string }[] };

@Tool({
  name: "list_queue",
  description: "List the open support tickets, most urgent first.",
  inputSchema: {},
  ui: {
    servingMode: "static",
    // Runs once, at startup, with ctx.output = {}.
    template: (ctx: TemplateContext<{}, Partial<Queue>>) => ctx.helpers.html`
      <h2 style="font: 600 18px system-ui">Open tickets</h2>
      <ul id="queue" style="font: 15px system-ui"></ul>
      <script>
        window.addEventListener("tool:result", (event) => {
          const items = event.detail.structuredContent.tickets.map((t) => {
            const item = document.createElement("li");
            item.textContent = t.id + " " + t.title;
            return item;
          });
          document.getElementById("queue").replaceChildren(...items);
        });
      </script>`,
  },
})
export class ListQueue extends ToolContext {
  async execute(): Promise<Queue> {
    return { tickets: [{ id: "T-1", title: "Cannot log in" }, { id: "T-3", title: "Login link expired" }] };
  }
}

In FrontMCP 1.9.4, those are the two real choices: "hybrid" is static with a small extra object for a few platforms, and the URL modes are served inline, and the server warns about both at startup. A server that serves every widget one way says so once, with @FrontMcp({ ui: { servingMode: "static" } }) or @App({ ui: { servingMode } }), and a tool's own servingMode still wins. Two more things matter wherever the page comes from. The page's own Content Security Policy lets it reach a few CDNs and the origins the tool lists in ui.csp, so list the ones the widget calls. And with an outputSchema, the widget gets only the fields it declares, as the model does: declare every field the widget shows.

Building widgets with React

A widget with state, like a queue with filters and a Close button on each row, is easier as a React component than as a script in a string. Point ui.template at a .tsx file and FrontMCP bundles it, and mounts the default export with the call's data. Hooks from @frontmcp/ui/react read the result and call tools through the host:

ui: { template: { file: join(__dirname, "queue.widget.tsx") } },

type Ticket = { id: string; title: string; priority: "high" | "normal" | "low" };
type Queue = { tickets: Ticket[] };

export default function QueueWidget({ output }: { output: Queue | null }) {
  if (!output?.tickets) return <p>Loading the queue…</p>;
  return (
    <ul>
      {output.tickets.map((t) => (
        <li key={t.id}>
          {t.id} {t.title} ({t.priority})
        </li>
      ))}
    </ul>
  );
}

The Playground can't run this: FrontMCP bundles widget files from the file system, on a Node server, and the Playground runs FrontMCP in your browser. The lesson's widgets were run in Node projects with FrontMCP 1.9.4, CommonJS and ES module, and rendered in Chromium, and its Playgrounds cover what runs here: the tools, and the calls a widget makes.

Template or React?

Whatever you choose, the result is still what the model reads, and many hosts show no widget at all. Make the tool useful without its page first.

What's next?

Start the chapter with Your First Widget. Every ui option is in the Tool UI reference, what each host and platform gets is on Hosts and platforms, and the React hooks and components are in Widget components. After this chapter, Built-in Plugins and Adapters covers the plugins that come with FrontMCP: caching, memory, approval, feature flags, CodeCall and OpenAPI.