Shipping Your First MCP App: Rendering Interactive UI Inside Claude and ChatGPT (SEP-1865)

How do I declare a UI resource on my MCP server?

You declare the UI as a resource with an HTML content type, then point a tool at it so the host knows to render that resource when the tool runs. The resource is the template, the tool result wires in the data.

In practice you register the UI once and reference it from the tool. Here is the shape of it using the TypeScript SDK. I have kept it deliberately small so the moving parts are visible.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({ name: "trip-planner", version: "1.0.0" });

// 1. The UI resource: a tiny self-contained web app
server.registerResource(
  "trip-form-ui",
  "ui://trip-planner/form",
  { mimeType: "text/html+mcp" },
  async () => ({
    contents: [{
      uri: "ui://trip-planner/form",
      mimeType: "text/html+mcp",
      text: TRIP_FORM_HTML, // your bundled HTML/JS string
    }],
  })
);

// 2. A tool that renders that UI and seeds it with data
server.registerTool(
  "plan_trip",
  {
    description: "Open the interactive trip planner",
    inputSchema: { destination: z.string() },
    _meta: { "mcp/ui": { resourceUri: "ui://trip-planner/form" } },
  },
  async ({ destination }) => ({
    content: [{ type: "text", text: `Opening planner for ${destination}` }],
    _meta: { "mcp/ui": { data: { destination, currency: "USD" } } },
  })
);

Two things to notice. First, the UI lives at a ui:// URI with an MCP-specific HTML mime type, so the host knows this resource is meant to be rendered, not read aloud. Second, the tool result carries a _meta payload that the host injects into the iframe at render time. That is how your form shows up pre-filled with the destination the model already parsed. The exact _meta key names are still settling as SDKs catch up to the formalized spec, so check your SDK version, but the structure (resource + render directive + seed data) is the stable part.

How does the sandboxed-iframe security model actually work?

The host renders your UI inside a sandboxed iframe with no direct access to the model, the conversation, the user's tokens, or your backend. The iframe can only communicate by posting structured messages to the host, which means a compromised or malicious UI cannot quietly exfiltrate anything.

This is the part I would slow down on, because it is where most people's instincts about "embedding a web app" are wrong. The iframe is treated as hostile by design. It runs with a restrictive sandbox, typically allowing scripts but blocking same-origin access, top-navigation, and direct network calls to arbitrary hosts. Your UI does not get a fetch line to your own API. If it wants data, it asks the host, and the host decides.

The contract between the iframe and the host is window.postMessage. Your UI posts a message up, the host validates it, and if it is a request to run a tool, the host routes it through the normal MCP machinery with the user's existing consent rules. Nothing about the App bypasses the trust boundary that already governs tool calls.

// Inside the sandboxed iframe (your UI bundle)
window.parent.postMessage({
  type: "tool/call",
  payload: { name: "book_trip", arguments: { destination, dates } }
}, "*");

// Receiving seed data and results back from the host
window.addEventListener("message", (event) => {
  const msg = event.data;
  if (msg.type === "render/data") hydrate(msg.payload);
  if (msg.type === "tool/result") showConfirmation(msg.payload);
});

A few rules I follow and would push on any team shipping these:

• Treat the iframe as untrusted on the host side, and treat the host as the only trusted peer on the iframe side. Validate event.origin and message shape on both ends.


• Never put secrets in the HTML bundle. It is shipped to the client and rendered in a box you do not control. API keys belong on the server, behind tool calls.


• Keep the UI dumb. It collects intent and displays results. The server decides what is allowed.

How do UI actions get audited the same way as tool calls?

Because every action a user takes in the App is converted by the host into a real tools/call request, it lands in the exact same audit, consent, and logging path as a tool the model would have invoked itself. There is no separate, weaker channel for "UI clicks."

This is the single most important design decision in SEP-1865, in my opinion, and it is the reason I trust Apps in a way I would not trust an arbitrary embedded webview. When a user clicks "Book" in my trip planner, the iframe does not book anything. It posts an intent. The host turns that intent into a tools/call for book_trip, applies whatever approval policy the user has configured (auto-approve, ask every time, blocked), and only then does my server's tool handler run.

So the audit trail is unified. Whether the model decided to call book_trip or the human clicked a button that called book_trip, you see one consistent record: same tool name, same arguments schema, same consent gate, same log line. For anyone who has to answer "what did this agent actually do," that single path is worth a lot. It also means your existing server-side validation, rate limits, and authorization checks on the tool cover the UI for free, because the UI cannot reach the handler any other way.

// One handler. Reached by the model OR by a user UI click. Audited identically.
server.registerTool("book_trip", { /* schema */ }, async (args, ctx) => {
  await assertUserCanBook(ctx.session);   // authz runs regardless of caller
  const booking = await db.createBooking(args);
  return { content: [{ type: "text", text: `Booked ${booking.id}` }] };
});

What changed when Apps and Tasks moved from experimental to official?

The headline change is status and stability. MCP Apps was announced as an official extension on 26 January 2026 and then formalized in the 2026-07-28 spec, which means clients can rely on it and render Apps without treating the feature as a moving experiment.

In practice, "experimental to official extension" changed three things for me as a builder:

1. Clients started rendering Apps for real. Before, you were building against a preview that a host might or might not support, and might break next release. Now the UI resource contract is something hosts commit to. That is the actual reason tutorial demand jumped: the surface finally renders in the products people use.


2. The interaction model got pinned down. The "UI action becomes a tools/call" routing, the sandboxed-iframe expectations, and the resource declaration are no longer suggestions. They are part of the spec you can build against and test against.


3. It rides the same 2026-07-28 baseline as the broader transport changes. If you are also moving servers to the new stateless model, the two efforts touch the same release, and I would do them together. I covered that side in my stateless 2026-07-28 migration field guide ↗.

What is the minimum end-to-end build, start to render?

The shortest honest path is five steps: build a UI bundle, expose it as a ui:// resource, attach it to a tool, return seed data from that tool, and handle the tools/call that comes back when the user interacts. That is the whole loop.

Here is the checklist I actually run through, in order: