Build MCP Apps: Add Interactive UIs to Any MCP Server (2026)

Standard MCP tools return text. That works for most cases. But when you need charts, forms, or dashboards, text falls short fast.

MCP Apps fix this. They are the first official extension to the Model Context Protocol. They let any MCP server return interactive HTML interfaces that render directly inside AI conversations.

I'm talking about real UIs. Filterable data tables. Live charts. Multi-step workflows. All running inside Claude, VS Code, or any supporting client — no separate tab required.

The spec is open and framework-agnostic. You can build MCP Apps with React, Vue, Svelte, or plain HTML. The SDK handles the communication layer. Your app runs in a sandboxed iframe with a clean JSON-RPC channel back to the MCP server.

This guide walks through everything you need to build your first MCP App: the architecture, the SDK, framework choices, security model, and real code examples from the official ext-apps repository.

What Are MCP Apps?

MCP Apps are an extension to the Model Context Protocol that adds interactive UI capabilities to MCP tool responses. Instead of returning only text, an MCP server can point to an HTML resource that the host renders inline.

Think of it this way. A regular MCP tool call returns: "Sales: $1.2M in Q1."

An MCP App returns that same data plus a live chart. You can filter by region, toggle metrics, and drill into individual deals — all without typing another prompt.

The key distinction from Claude Artifacts: MCP Apps serve live data from external servers. They are not static HTML generated by the model. They update in real time and can call back to MCP tools for fresh data.

For a full overview of MCP Apps and the launch partners, see the Claude MCP Apps full guide.

How MCP Apps Work Under the Hood

MCP Apps combine two existing MCP primitives in a new way.

Primitive 1: Tools With UI Metadata

When you define an MCP tool, you add a _meta.ui.resourceUri field to the tool description. This tells the host: "this tool has a UI component."

Primitive 2: UI Resources

The server exposes HTML/JS bundles via the ui:// scheme. The host fetches these resources and renders them in a sandboxed iframe.

The Full Request Flow

Here's what happens when a user triggers a tool with MCP Apps support:

1. LLM decides to call a tool that has _meta.ui.resourceUri in its description
2. Host preloads the UI resource — this can start before the tool call even completes
3. Tool executes and returns text content plus structured data
4. Host renders the HTML resource in a sandboxed iframe within the conversation
5. Host pushes tool results to the app via postMessage
6. User interacts — clicks buttons, filters data, submits forms
7. App calls MCP tools through the host's JSON-RPC bridge
8. Host forwards tool calls to the MCP server
9. Fresh data flows back to the app and the UI updates

Communication uses a JSON-RPC dialect specific to MCP Apps. Some methods share names with core MCP (like tools/call). Others are app-specific (like ui/initialize). The transport is postMessage instead of stdio or HTTP.

The _meta.ui object also supports:

• permissions — request capabilities like microphone or camera access
• csp — specify allowed external origins for loading scripts and resources

// Standard MCP tool response (before MCP Apps)
{
  content: [{ type: "text", text: "Signups: 1,204 in January" }]
}

// MCP App tool response (with interactive UI)
{
  content: [{ type: "text", text: "Here are your January signups" }],
  _meta: {
    ui: {
      resourceUri: "ui://dashboard/signup-chart"
    }
  }
}

Why MCP Apps Beat Standalone Web Apps

You could build a regular web app and drop a link in the chat. But MCP Apps give you four things a standalone app can't match.

If your use case doesn't benefit from these properties, a regular web app is simpler. But for anything that belongs in the conversation flow, MCP Apps are the better choice.

Build Your First MCP App Step by Step

Here's the minimum viable MCP App using the official SDK.

Step 1 — Create Your MCP Server With a UI-Enabled Tool

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

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

// Register the UI resource
server.resource("dashboard-ui", "ui://dashboard", async (uri) => ({
  contents: [{
    uri: uri.href,
    mimeType: "text/html",
    text: dashboardHtml  // your bundled HTML string
  }]
}));

// Register a tool that references the UI
server.tool(
  "show_dashboard",
  "Show an interactive dashboard",
  {
    _meta: {
      ui: { resourceUri: "ui://dashboard" }
    }
  },
  { month: z.string() },
  async ({ month }) => ({
    content: [{
      type: "text",
      text: `Dashboard data for ${month}`
    }]
  })
);

The _meta.ui.resourceUri field tells the host where to find the HTML interface. The host can preload this resource as soon as it sees the tool description.

Step 2 — Build Your HTML Interface

Your UI is a standard HTML page. Use the App class from the SDK to communicate with the host:

<!DOCTYPE html>
<html>
<body>
  <div id="chart"></div>
  <button id="refresh">Refresh Data</button>

  <script type="module">
    import { App } from "@modelcontextprotocol/ext-apps";

    const app = new App();

    // Receive tool results from the host
    app.onToolResult((result) => {
      renderChart(result.data);
    });

    // Call an MCP tool from the UI
    document.getElementById("refresh")
      .addEventListener("click", async () => {
        const result = await app.callTool(
          "get_latest_data",
          { month: "april" }
        );
        renderChart(result);
      });

    // Update the model's context
    app.updateContext(
      "User filtered the dashboard to April data"
    );
  </script>
</body>
</html>

Step 3 — Connect and Test

Bundle your HTML, serve it from your MCP server as a ui:// resource, and connect with any supporting client. The host handles iframe sandboxing, message routing, and security automatically.

Choose Your Framework

MCP Apps are framework-agnostic. The official ext-apps repository includes starter templates for six options:

Each template shows the recommended patterns for that framework's reactivity system. They're starting points, not requirements.

The App class from @modelcontextprotocol/ext-apps is a convenience wrapper. You can implement the postMessage protocol directly if you prefer zero dependencies.

The MCP Apps SDK and Tooling

Two packages cover most use cases when building MCP Apps.

@modelcontextprotocol/ext-apps — For Building Apps

• App class handles initialization, message routing, and tool calls
• Works in any framework or plain JavaScript
• Implements the full JSON-RPC protocol over postMessage
• Provides hooks for receiving tool results, calling tools, and updating model context

@mcp-ui/client — For Building Hosts That Render Apps

• React components for rendering MCP App views inside your own client
• Handles iframe sandboxing and message passing automatically
• See the MCP-UI documentation for integration details

App Bridge — Lower-Level Host Integration

• Manages iframe lifecycle, security policy enforcement, and tool call proxying
• Use this if you're building a non-React host or need finer control
• See the basic-host example in the ext-apps repository

Real MCP Apps Examples Worth Studying

The official ext-apps repository has production-quality examples. Each one is a complete, runnable MCP server you can clone and run locally.

Start with basic-server-vanillajs to understand the protocol. Then move to your framework of choice.

Security Model: Sandboxed Iframes and User Consent

MCP Apps run in a sandboxed iframe. That's the foundation of the entire security model.

What the Sandbox Prevents

• No access to the parent window's DOM
• No reading of host cookies or localStorage
• No navigation of the parent page
• No script execution in the parent context

Communication Channel

All messages between app and host go through postMessage. The host controls which capabilities the app can access. It can restrict which tools an app calls or disable specific features entirely.

For a deeper look at MCP server security, see the complete security guide.

Which Clients Support MCP Apps in 2026?

MCP Apps is an extension to the core MCP specification. Support varies by client.

If you're building an MCP client and want to render MCP Apps, use @mcp-ui/client (React) or the App Bridge module (framework-agnostic). Check the client matrix for the latest support status.

When Should You Use MCP Apps?

MCP Apps shine in five scenarios. For everything else, regular MCP tools are sufficient.

Test Your MCP App With MCP Playground

Connect your MCP App server to MCP Playground to inspect tools and resources before deploying to production clients.

1. Go to MCP Playground
2. Enter your server's endpoint URL
3. Browse tools — verify that _meta.ui.resourceUri appears in tool descriptions
4. Call a tool — check both the text response and the UI resource pointer

This catches configuration issues early, before users hit them in Claude or VS Code.

Frequently Asked Questions

Build Something Users Can See

MCP Apps are the biggest expansion of what MCP servers can do since the protocol launched. They turn text-only tool responses into interactive experiences — dashboards, forms, visualizations — all running inside the conversation.

The SDK is stable. The spec is open. Six clients already support rendering. If you're building MCP servers, adding a UI layer is straightforward.

Related Guides

• Claude MCP Apps — Full Guide (Launch Partners, How It Works)
• What Is the Model Context Protocol (MCP)?
• Build an MCP Server on Cloudflare Workers
• MCP Server Security — Complete Guide
• Deploy MCP Servers — Vercel, Railway, Render, Heroku, Fly.io
• MCP 2026 Roadmap — What's Changing for Developers