mcp-ui: An SDK for Rendering Interactive HTML UI Inside MCP Tool Responses

The Problem: MCP Tools Return Text, Not Interfaces

MCP (Model Context Protocol) tools return text content to an AI host. That is adequate for data retrieval and code generation, but it cannot display a form, a chart, or a widget that the user interacts with before continuing. mcp-ui addresses this gap by defining a wire format that attaches an HTML interface to a tool result.

The library is for engineers building MCP servers who want tool results that can display interactive UI alongside the AI conversation. Examples include a tool that retrieves a calendar and shows a week view the user can click on, or a tool that pulls product data and renders a comparison widget.

The README states that mcp-ui pioneered the concept of interactive UI over MCP, and that the patterns developed here directly influenced the MCP Apps specification published at github.com/modelcontextprotocol/ext-apps. The @mcp-ui/* packages are described as fully compliant with the MCP Apps specification and ready for production use.

Core Wire Format: UIResource and the MCP Apps Pattern

The underlying payload is a UIResource, a JSON object with a fixed structure:

interface UIResource {
  type: 'resource';
  resource: {
    uri: string;       // e.g., ui://component/id
    mimeType: 'text/html;profile=mcp-app';
    text?: string;     // HTML content
    blob?: string;     // Base64-encoded HTML content
  };
}

The uri field uses a ui:// scheme as a unique identifier. The mimeType text/html;profile=mcp-app is the MCP Apps standard MIME type that a compliant host recognises as renderable UI. The text field holds plain HTML; the blob field holds Base64-encoded HTML for binary-safe transport.

The MCP Apps pattern links a tool to its UI via the _meta.ui.resourceUri field in the tool's response. When the host detects that field, it fetches the UI via a resources/read call and renders it alongside the tool result. This decouples the tool logic from the UI delivery: the tool returns its data payload, and the host fetches the UI independently.

Server-Side Setup with @mcp-ui/server

The @mcp-ui/server package provides createUIResource as the main entry point for creating a UIResource from HTML content. The README shows how to register both the resource handler and the tool using the @modelcontextprotocol/ext-apps/server package:

import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';

const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  content: { type: 'rawHtml', htmlString: '<h1>Widget</h1>' },
  encoding: 'text',
});

registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
  contents: [widgetUI.resource]
}));

registerAppTool(server, 'show_widget', {
  description: 'Show widget'

The registerAppTool call links the tool to the registered resource via the _meta.ui.resourceUri mechanism. The host sees the tool result, finds the _meta field, fetches the widget_ui resource, and renders the HTML.

Ruby and Python packages (mcp_ui_server and mcp-ui-server) are also available for server-side resource creation in those languages, following the same pattern.

Client-Side Rendering: AppRenderer and UIResourceRenderer

On the host side, mcp-ui provides two React components: AppRenderer for MCP Apps-compliant hosts and UIResourceRenderer for legacy hosts.

AppRenderer is the current recommended component:

import { AppRenderer } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  return (
    <AppRenderer
      client={client}
      toolName={toolName}
      sandbox={{ url: sandboxUrl }}
      toolInput={toolInput}
      toolResult={toolResult}
      onOpenLink={async ({ url }) => window.open(url)}
      onMessage={async (params) => console.log('Message:', params)}
    />
  );
}

The sandbox prop takes a proxy URL. The HTML is rendered inside an iframe for isolation, which is the mechanism described in the Supported Resource Types section: content is displayed inside an HTMLResourceRenderer that wraps an iframe. This is the security boundary between the tool's HTML and the host application.

UIResourceRenderer handles the older pattern where the HTML was embedded directly in the tool response rather than fetched via a resource URI. It also ships as a Web Component for non-React hosts:

<ui-resource-renderer
  resource='{ "mimeType": "text/html", "text": "<h2>Hello!</h2>" }'
></ui-resource-renderer>

UI Actions: Communication From the HTML Back to the Agent

Static HTML inside a tool response cannot call back to the AI agent. mcp-ui adds a bidirectional channel via postMessage events. The UI snippet sends events from inside the iframe; the host intercepts them via the onMessage and onUIAction callbacks.

The README describes UI action types: tool call, prompt, link, notify, and intent. A button in the HTML that should trigger another tool call sends a postMessage of type tool with a toolName and params. The host receives this via onUIAction and routes it back to the MCP server.

For hosts that use a platform-specific API rather than the open postMessage protocol, mcp-ui provides platform adapters. The Apps SDK Adapter translates mcp-ui's postMessage calls to the Apps SDK API (targeting environments such as ChatGPT) and works transparently without changes to the existing HTML. The README notes that as hosts become compatible with the open specification, these adapters will become unnecessary.

Limitations and Where the MCP Apps Pattern Does Not Apply

mcp-ui only produces value when the host renders the UI. An MCP server that returns UIResource objects to a host with no AppRenderer support sends HTML that the host ignores or displays as raw text. The README section on Supported Hosts covers which environments are compatible.

The iframe sandboxing is a security control but also a constraint: the HTML inside the iframe cannot access the host page's DOM, cookies, or storage directly. Any interaction with the host must go through the postMessage channel. That channel is appropriate for tool calls and prompts but is not a general-purpose bridge.

The project is at client/v7.1.1 for the client package. The server package has its own versioning. The Ruby and Python packages each have separate version histories. A monorepo consumer who depends on multiple packages must track compatibility across those version lines.

Finally, the MCP Apps standard is relatively new. Host adoption is ongoing, and the adapter layer exists precisely because production hosts do not all implement the standard yet.

Alternatives and How mcp-ui Positions Itself

The RELATED SEARCHES mention mcp-ui vs ag-ui and mcp-ui vs generative ui. ag-ui is a separate protocol for agent-to-UI communication that operates at a different layer: it defines how a frontend framework subscribes to an agent's event stream. mcp-ui operates at the MCP layer, attaching UI to specific tool responses rather than streaming agent events to a general-purpose frontend.

Generative UI, as implemented in frameworks like AI SDK from Vercel, allows the model to select and render React components as part of its response. The difference from mcp-ui is execution model: generative UI requires the host to ship a component library that the model can reference, while mcp-ui delivers self-contained HTML over the resource protocol without requiring the host to maintain a component registry.

The README positions mcp-ui as pioneering the pattern and influencing the MCP Apps standard. Teams choosing between approaches should evaluate host compatibility first: mcp-ui targets the MCP protocol specifically, while generative UI and ag-ui target different integration surfaces.

Editorial conclusion

mcp-ui is the right choice for teams building MCP servers that need richer output than plain text, particularly where the host application already supports MCP Apps. The @mcp-ui/client v7 series is described as ready for production use. Teams building for hosts that do not yet implement MCP Apps should evaluate the adapter coverage before committing, since the platform adapter layer adds translation code that will eventually become unnecessary as hosts adopt the open standard. The first step is installing @mcp-ui/server and calling createUIResource with a rawHtml content type to verify the wire format works in the target host.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. MCP-UI-Org/mcp-ui on GitHub
3. Project website
4. README
5. Releases