@mcp-ui/client

@mcp-ui/client is the client-side half of the mcp-ui project, a React SDK that renders interactive, sandboxed UI returned by Model Context Protocol (MCP) tools inside a host application (chat UI, IDE panel, agent console). It provides AppRenderer and AppFrame React components that fetch a tool’s UI resource, mount it in a sandboxed iframe, and bridge postMessage-based communication between the guest UI and the host’s MCP client — forwarding tool calls, resource reads, prompts, and notifications.

mcp-ui pioneered the pattern of shipping interactive UI over MCP and, per its own README, directly influenced the subsequent MCP Apps specification that standardized UI delivery over the protocol. The client package is one of several SDKs in the mcp-ui monorepo (alongside @mcp-ui/server, plus Ruby and Python server SDKs), and is maintained under the dedicated MCP-UI-Org GitHub organization with an active Discord community.

What You Get

• AppRenderer React component that wires an MCP Client to a tool’s rendered UI, forwarding tool calls, resource/prompt requests, and notifications via an imperative handle
• AppFrame lower-level sandboxed-iframe component with configurable SandboxConfig for embedding guest UI safely
• isUIResource() / getUIResourceMetadata() utilities for detecting and reading metadata off MCP resources before rendering
• Re-exported AppBridge and PostMessageTransport from @modelcontextprotocol/ext-apps for advanced host/guest communication scenarios
• TypeScript types for the full MCP Apps message surface (tool list changes, resource list changes, size-changed notifications, partial tool-input streaming)

Common Use Cases

• Building an AI chat UI or IDE integration that renders rich, interactive widgets returned by MCP tools instead of plain text
• Embedding third-party or user-generated tool UI safely via sandboxed iframes with a defined postMessage protocol
• Detecting whether an MCP resource is a renderable UI resource before deciding how to display it in a host application
• Implementing a host application compliant with the MCP Apps specification that mcp-ui helped originate

Under The Hood

Architecture — AppRenderer (sdks/typescript/client/src/components/AppRenderer.tsx) is the primary integration point: it accepts an MCP Client, a toolName, and a SandboxConfig, then either fetches the tool’s UI resource itself (via getToolUiResourceUri/readToolUiResourceHtml in utils/app-host-utils.ts) or accepts pre-fetched HTML directly. It delegates the actual sandboxed rendering to AppFrame, and wires an AppBridge (imported from the sibling @modelcontextprotocol/ext-apps package) to forward MCP protocol messages — tool calls, resource reads, prompt lists, list-changed notifications — between the guest iframe and the host’s MCP client, exposing an imperative AppRendererHandle (sendToolListChanged, sendResourceListChanged, teardownResource) for host-driven updates. utils/isUIResource.ts and utils/metadataUtils.ts provide resource-type detection and metadata extraction as standalone helpers usable without the full renderer.

Tech Stack — TypeScript/React (React 18 peer dependency), built with Vite and vite-plugin-dts for dual ESM/CJS output plus type declarations, depending on @modelcontextprotocol/sdk and @modelcontextprotocol/ext-apps for MCP protocol types and the app-bridge transport, and zod for schema validation. Tests run under Vitest with @testing-library/react and jsdom.

Code Quality — The package has parallel __tests__ directories alongside its source modules (components/__tests__/AppRenderer.test.tsx, components/__tests__/AppFrame.test.tsx, components/__tests__/ProxyScript.test.ts, utils/__tests__/isUIResource.test.ts, utils/__tests__/metadataUtils.test.ts, utils/__tests__/app-host-utils.test.ts), giving direct coverage of both the rendering components and the utility functions. The parent monorepo is released via semantic-release (visible from the semantic-release-bot’s high commit count) with 92 GitHub releases, indicating a disciplined, automated release cadence.

API Design — The high-level path is a single <AppRenderer client={mcpClient} toolName="..." sandbox={...} /> component, so hosts get working sandboxed rendering with minimal setup, while AppFrame and the re-exported AppBridge/PostMessageTransport are available for teams that need lower-level control over the host/guest message bridge. The tradeoff is a moderate learning curve tied to understanding the broader MCP Apps message protocol (tool calls, resource reads, size-changed notifications) that this package forwards rather than abstracts away entirely.