What Is mcp-ui • Installation • Quickstart • Core Concepts • Example Implementation • Roadmap • Contributing • License
mcp-ui brings interactive web components to Model Context Protocol (MCP). Deliver rich, dynamic UI resources directly from your MCP server to be rendered by the client. Take Human<>AI interaction to the next level!
This project is an experimental playground for MCP UI ideas. Expect rapid iteration and community-driven enhancements!
mcpui-x.mp4
mcp-ui is a TypeScript SDK comprising two packages:
@mcp-ui/server: Utilities to generateHtmlResourceBlockobjects on your MCP server.@mcp-ui/client: UI components (e.g.,<HtmlResource />) to render those blocks in the browser and handle their events.
Together, they let you define reusable UI resource blocks on the server side, seamlessly display them in the client, and react to their actions in the MCP host environment.
The primary payload exchanged between the server and the client:
interface HtmlResourceBlock {
type: 'resource';
resource: {
uri: string; // e.g. "ui://component/id" or "ui-app://app/instance"
mimeType: 'text/html';
text?: string; // Inline HTML or external URL
blob?: string; // Base64-encoded HTML or URL (for large payloads)
};
}uri: Unique identifier for caching and routingui://…— self-contained HTML (rendered via<iframe srcDoc>)ui-app://…— external app/site (rendered via<iframe src>)
mimeType: Alwaystext/htmltextvs.blob: Choosetextfor simple strings; useblobfor larger or encoded content.
It's rendered in the client with the <HtmlResource> React component.
The HTML method is limited, and the external app method isn't secure enough for untrusted 3rd party sites. We need a better method. Some ideas we should explore: RSC, remotedom, etc.
UI blocks must be able to interact with the agent. In mcp-ui, this is done by hooking into events sent from the UI block and reacting to them in the host. For example, an HTML may trigger a tool call when a button is clicked by sending an event which will be caught handled by the client.
# using npm
npm install @mcp-ui/server @mcp-ui/client
# or yarn
yarn add @mcp-ui/server @mcp-ui/client-
Server-side: Build your resource blocks
import { createHtmlResource } from '@mcp-ui/server'; // Inline HTML const direct = createHtmlResource({ uri: 'ui://greeting/1', content: { type: 'directHtml', htmlString: '<p>Hello, MCP UI!</p>' }, delivery: 'text', }); // External URL const external = createHtmlResource({ uri: 'ui-app://widget/session-42', content: { type: 'externalUrl', iframeUrl: 'https://example.com/widget' }, delivery: 'text', });
-
Client-side: Render in your MCP host
import React from 'react'; import { HtmlResource } from '@mcp-ui/client'; function App({ mcpResource }) { if ( mcpResource.type === 'resource' && mcpResource.resource.mimeType === 'text/html' ) { return ( <HtmlResource resource={mcpResource.resource} onUiAction={(tool, params) => { console.log('Action:', tool, params); return { status: 'ok' }; }} /> ); } return <p>Unsupported resource</p>; }
-
Enjoy interactive MCP UIs — no extra configuration required.
Client example modelcontextprotocol/inspector#413
Server example Try out the hosted app at -
- HTTP Streaming:
https://remote-mcp-server-authless.idosalomon.workers.dev/mcp - SSE:
https://remote-mcp-server-authless.idosalomon.workers.dev/sse
The app is deployed from examples/server.
Drop those URLs into any MCP-compatible host to see mcp-ui in action.
- Support new SSR methods (e.g., RSC)
- Support additional client-side libraries
- Expand UI Action API
- Do more with Resources and Sampling
Contributions, ideas, and bug reports are welcome! See the contribution guidelines to get started.
Apache License 2.0 © The MCP UI Authors
This project is provided “as is”, without warranty of any kind. The mcp-ui authors and contributors shall not be held liable for any damages, losses, or issues arising from the use of this software. Use at your own risk.