MCP Apps Explained: Interactive UIs Rendered Inside Chat, Standardized as SEP-1865

MCP Apps is an official extension to the Model Context Protocol (SEP-1865, Extensions Track, status Final): an MCP server declares a ui:// resource in its tool description, and the host renders that interactive HTML inside the conversation in a sandboxed iframe — dashboards, forms, and visualizations that live in the chat itself and can call server tools in return. This article is a section-by-section reading of the official overview, the SEP-1865 text, and the official build guide, all fetched on 2026-09-14. Code examples are quoted from the guide (documentation-checked, not machine-verified), and only claims reproducible from those sources are included.

1. The problem MCP Apps solves

The official overview opens with the limitation: text responses can only go so far — sometimes users need to interact with data, not just read about it. Traditional MCP tools return text, images, or structured data that the host displays; MCP Apps extends the pattern so a tool declares a reference to an interactive UI that the host renders in place.

The obvious question is why not just build a web app and send a link. The docs give four reasons:

The docs are equally clear about the boundary: if your use case does not benefit from these properties, a regular web app might be simpler. MCP Apps earn their keep when tight integration with the LLM conversation matters.

2. How MCP Apps work: ui:// resources, tool metadata, sandboxed rendering

The official overview frames the core pattern as a combination of two MCP primitives: a tool that declares a UI resource in its description, plus a UI resource that renders data as an interactive HTML interface. When the model decides to call a tool that supports MCP Apps, four things happen:

1. UI preloading: the tool description includes a _meta.ui.resourceUri field pointing at a ui:// resource. The host can preload it before the tool is even called, which enables features like streaming tool inputs to the app.
2. Resource fetch: the host fetches the UI resource from the server. It is an HTML page, often bundled with its JavaScript and CSS for simplicity; apps can also load external scripts from origins specified in _meta.ui.csp.
3. Sandboxed rendering: web hosts typically render the HTML inside a sandboxed iframe within the conversation. The resource's _meta.ui object can carry permissions to request additional capabilities (microphone, camera) and csp to control which external origins the app may load from.
4. Bidirectional communication: the app and host talk over a JSON-RPC protocol that forms its own dialect of MCP — some requests and notifications are shared with the core protocol (for example tools/call), some are similar (ui/initialize), and most are new methods with a ui/ prefix. The app can request tool calls, send messages, update the model's context, and receive data from the host.

A typical exchange, in the official diagram's terms: the user asks to see analytics, the model calls the tool, the server returns a result, the host pushes it to the app; the user clicks and drills down inside the app; the app issues a tools/call request, the host forwards it, fresh data comes back and the UI updates in place; and the app can send a context update back to the model.

3. Three design decisions recorded in SEP-1865

SEP-1865 (created 2025-11-21, status Final, nine authors, Extensions Track) records the trade-offs made during standardization. Three are worth reading closely:

• Predeclared resources, not embedded ones or resource links: UI is modeled as predeclared ui:// resources referenced by tools via metadata. Hosts can prefetch templates before tool execution, presentation is separated from data (helping caching), and UI resources can be security-reviewed before rendering. Rejected alternatives: embedded resources (the then-current MCP-UI approach — convenient for servers, but with gaps in performance optimization and the UI review process) and resource links (same gaps).
• Reuse MCP's JSON-RPC, not a custom protocol: this reuses existing type definitions and SDK infrastructure, and JSON-RPC brings timeouts and error handling for free. Rejected alternatives: a custom message protocol (MCP-UI's tool/intent/prompt types translate to a subset of the proposed JSON-RPC messages) and a global API object (requires host-specific injection and cannot work with external iframe sources).
• HTML-only MVP: HTML is universally supported, has the simplest security model (a standard iframe sandbox), allows screenshot and preview generation, and covers most observed use cases. External URLs were deferred over concerns about model visibility, screenshots, and the review process — they may effectively arrive via the new externalIframes capability.

The SEP's motivation section also explains where the standard came from: the community project MCP-UI demonstrated the viability and value of UI resources and bidirectional communication, with adopters including Postman, HuggingFace, Shopify, Goose, and ElevenLabs; OpenAI's Apps SDK, launched in November 2025 with MCP as its backbone, further validated demand for rich UIs inside conversational AI. MCP Apps unifies both lineages into a single open standard, fixing the fragmentation where servers could not rely on UI support, hosts behaved slightly differently, security and audit patterns were inconsistent, and developers maintained separate implementations. As an extension it is optional and backwards-compatible, negotiated explicitly through the extension capabilities mechanism.

4. Build an MCP App (code from the official guide)

The build guide asks for Node.js 18 or higher and recommends familiarity with MCP tools and resources, since MCP Apps combine both primitives. Dependencies:

npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk
npm install -D typescript vite vite-plugin-singlefile express cors @types/express @types/cors tsx

The ext-apps package provides both server-side helpers (registering tools and resources) and the client-side App class for UI-to-host communication. Vite with vite-plugin-singlefile bundles the UI into a single HTML file here purely for convenience — it is optional, and you can use any bundler or serve unbundled files once CSP and CORS are configured.

The server does two things: register a tool that includes the _meta.ui.resourceUri field, and register a resource handler that serves the bundled HTML. The guide's complete server file (server.ts):

// server.ts
console.log("Starting MCP App server...");

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import {
  registerAppTool,
  registerAppResource,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
import cors from "cors";
import express from "express";
import fs from "node:fs/promises";
import path from "node:path";

const server = new McpServer({
  name: "My MCP App Server",
  version: "1.0.0",
});

// The ui:// scheme tells hosts this is an MCP App resource.
// The path structure is arbitrary; organize it however makes sense for your app.
const resourceUri = "ui://get-time/mcp-app.html";

// Register the tool that returns the current time
registerAppTool(
  server,
  "get-time",
  {
    title: "Get Time",
    description: "Returns the current server time.",
    inputSchema: {},
    _meta: { ui: { resourceUri } },
  },
  async () => {
    const time = new Date().toISOString();
    return {
      content: [{ type: "text", text: time }],
    };
  },
);

// Register the resource that serves the bundled HTML
registerAppResource(
  server,
  resourceUri,
  resourceUri,
  { mimeType: RESOURCE_MIME_TYPE },
  async () => {
    const html = await fs.readFile(
      path.join(import.meta.dirname, "dist", "mcp-app.html"),
      "utf-8",
    );
    return {
      contents: [
        { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
      ],
    };
  },
);

// Expose the MCP server over HTTP
const expressApp = express();
expressApp.use(cors());
expressApp.use(express.json());

expressApp.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true,
  });
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

expressApp.listen(3001, (err) => {
  if (err) {
    console.error("Error starting server:", err);
    process.exit(1);
  }
  console.log("Server listening on http://localhost:3001/mcp");
});

Per the guide's own breakdown: resourceUri uses the ui:// scheme to tell hosts this is an MCP App resource, with an arbitrary path structure; registerAppTool registers the tool carrying _meta.ui.resourceUri — when the host calls it, the UI is fetched and rendered and the tool result is passed to it; registerAppResource serves the bundled HTML when the host requests the UI resource; and the Express server exposes MCP over HTTP on port 3001 at /mcp.

The UI side is an HTML page plus a TypeScript module using the App class to talk to the host (src/mcp-app.ts):

// src/mcp-app.ts
import { App } from "@modelcontextprotocol/ext-apps";

const serverTimeEl = document.getElementById("server-time")!;
const getTimeBtn = document.getElementById("get-time-btn")!;

const app = new App({ name: "Get Time App", version: "1.0.0" });

// Establish communication with the host
app.connect();

// Handle the initial tool result pushed by the host
app.ontoolresult = (result) => {
  const time = result.content?.find((c) => c.type === "text")?.text;
  serverTimeEl.textContent = time ?? "[ERROR]";
};

// Proactively call tools when users interact with the UI
getTimeBtn.addEventListener("click", async () => {
  const result = await app.callServerTool({
    name: "get-time",
    arguments: {},
  });
  const time = result.content?.find((c) => c.type === "text")?.text;
  serverTimeEl.textContent = time ?? "[ERROR]";
});

Three points, in the guide's words: app.connect() establishes communication with the host — call it once when your app initializes; app.ontoolresult fires when the host pushes a tool result (for example when the tool is first called and the UI renders); app.callServerTool() lets the app proactively call tools — each call is a round-trip to the server, so design the UI to handle latency gracefully. The App class also provides methods for logging, opening URLs, and updating the model's context with structured data from your app. Frameworks are not binding: the protocol is standard web primitives, and the official examples include starter templates for React, Vue, Svelte, Preact, Solid, and vanilla JavaScript.

5. The security model: sandbox, CSP, auditable traffic

The security model deserves its own section because it answers why a host can safely render third-party UI:

• Iframe sandbox isolation: the app cannot access the parent window's DOM, read the host's cookies or localStorage, navigate the parent page, or execute scripts in the parent context.
• postMessage-only communication: the host controls which capabilities the app gets — for example, restricting which tools an app may call, or disabling the sendOpenLink capability.
• Deny-by-default CSP: the build guide states the UI resource will be rendered in a secure iframe with deny-by-default CSP configuration; external resources must be declared explicitly.
• SEP threat-model mitigations: restricted sandbox permissions, predeclared templates that hosts can review before rendering, fully loggable (and therefore auditable) JSON-RPC traffic, and optional explicit user consent for UI-initiated tool calls.

For the broader threat landscape (Confused Deputy, Token Passthrough, SSRF, and the other official attack vectors), pair this with the site's MCP security guide — MCP Apps' sandbox addresses the layer where untrusted content enters host rendering, which complements rather than replaces server-side mitigations.

6. Testing and host support

The guide offers two test paths. The first is the official basic-host: clone the ext-apps repository, install dependencies under examples/basic-host, point the SERVERS environment variable at your server, run npm start, and open localhost port 8080 to pick a tool, call it, and watch your app render in a sandboxed iframe. The second is a real host, Claude: expose the local server with a cloudflared tunnel and add the generated URL as a custom connector in Claude (the guide notes custom connectors are available on paid Claude plans).

npx cloudflared tunnel --url http://localhost:3001

As of 2026-09-14, the official site lists 8 hosts supporting MCP Apps:

To add MCP Apps support to your own host, the guide offers two routes: the community @mcp-ui/client React components for rendering and interacting with app views, or the official SDK's AppBridge module, which handles rendering apps in sandboxed iframes, message passing, tool-call proxying, and security policy enforcement — the basic-host example shows the integration.

Two anchors for engineering activity (checked 2026-09-14): the latest npm release of @modelcontextprotocol/ext-apps is 2.0.0, published 2026-09-08; the ext-apps repository was last pushed 2026-09-09, and the build guide notes the extension is under active development.

7. Where MCP Apps sits: one piece of the extensions system

MCP Apps is not an isolated proposal but part of the MCP extensions system (the Extensions Track defined by SEP-2133). The official extensions directory also lists: Tasks (SEP-2663, asynchronous task execution for long-running MCP operations), Skills (SEP-2640, discovering and reading Agent Skills from MCP servers), OAuth Client Credentials (machine-to-machine authentication), and Enterprise-Managed Authorization (centralized access control via enterprise identity providers) — with per-client implementation status tracked on the official client-matrix page. Readers interested in how features move between the core spec and the extensions track can compare with the site's coverage of client-feature status.

The docs also make building MCP Apps with an AI coding agent a first-class path: the create-mcp-app skill bundles architecture guidance, best practices, and working examples; Claude Code can install it from the plugin marketplace, and other agents can get it via the Vercel Skills CLI or a manual copy — the skills-directory table covers VS Code / GitHub Copilot, Gemini CLI, Cline, Goose, Cursor, and Codex (~/.codex/skills/). For this site's readers, that is a direct intersection between Codex and the MCP ecosystem.

The official examples directory offers 15 runnable examples across five categories: 3D and visualization (a CesiumJS globe, Three.js scenes, shader effects), data exploration (cohort heatmaps, customer segmentation, a wiki explorer), business applications (scenario modeling, budget allocation), media (PDF, video, sheet music, text-to-speech), and utilities (QR codes, system monitoring, speech-to-text).

8. What this means for readers

Keeping claims inside what is verifiable today: the MCP homepage (2026-09-14) lists ChatGPT among the AI assistants that support MCP — that is protocol-level connectivity. The same day's MCP Apps host list (the 8 hosts above) does not include ChatGPT; these two statements must not be conflated. The most direct OpenAI-side connection is the fact recorded in SEP-1865's own text: the Apps SDK uses MCP as its backbone, and its architecture significantly informed this specification. Beyond that, Codex supports a skills directory where the official create-mcp-app skill can be installed — another intersection between OpenAI's toolchain and the MCP Apps workflow. The site's world state now records the key MCP Apps facts (updated 2026-09-14).

9. Next steps

• The protocol itself, and the tools/resources primitives: Model Context Protocol: how MCP works and how to build on it
• Build an MCP server from scratch (the base for the server-side pattern here): Build Your Own MCP Server: From Zero to Published
• The other side of the extensions track — features being born and retired in the core spec: MCP Client Features Today: Elicitation Stays, Roots and Sampling Deprecated (SEP-2577)