mcp-ui is a TypeScript SDK that adds UI capabilities to the Model-Context Protocol (MCP). It provides packages to create interactive HTML components on the server and handle their rendering on the client.
This project is a playground for new ideas in the MCP community. Expect it to evolve rapidly!
mcpui-x.mp4
Make it simple to create and render HTML resource blocks. These are special objects you can send in an MCP response, letting your MCP server deliver a structured interactive web component for the host to display.
This is the main object exchanged between server and client:
interface HtmlResource {
type: 'resource';
resource: {
uri: string; // e.g., "ui://my-component/1" or "ui-app://my-app/instance-1"
mimeType: 'text/html';
text?: string; // HTML content OR external app URL
blob?: string; // Base64 encoded HTML content or external app URL
};
}uri: Uniquely identifies the resource.ui://...means the content is self-contained HTML (rendered withsrcDocin an iframe).ui-app://...means the content is an external app or site (rendered withsrcin an iframe).
mimeType: Always"text/html"for this SDK.textvs.blob: Usetextfor direct strings, orblobfor Base64-encoded content (handy for larger payloads or to avoid JSON issues).
@mcp-ui/client: React components for the client. The main export is<HtmlResource />—just drop it into your app to render MCP HTML resources.@mcp-ui/server: Helpers for buildingHtmlResourceobjects on the server.
- Clone the repo:
git clone https://github.com/idosal/mcp-ui.git cd mcp-ui - Install dependencies:
pnpm install
Use createHtmlResource to build a resource block:
import { createHtmlResource } from '@mcp-ui/server';
// Direct HTML content
const directHtmlResource = createHtmlResource({
uri: 'ui://my-unique-component/instance1',
content: { type: 'directHtml', htmlString: '<p>Hello from direct HTML!</p>' },
delivery: 'text',
});
// External App URL
const appUrl = 'https://example.com/my-interactive-app';
const externalAppResource = createHtmlResource({
uri: 'ui-app://my-app-identifier/session123',
content: { type: 'externalUrl', iframeUrl: appUrl },
delivery: 'text',
});The main export is the <HtmlResource /> React component. Use it to render any MCP HTML resource block:
import React from 'react';
import { HtmlResource } from '@mcp-ui/client';
const MyComponent = ({ mcpResource }) => {
const handleAction = async (tool, params) => {
console.log('Action from iframe:', tool, params);
// Handle actions posted from the iframe content
return { status: 'Action handled' };
};
if (
mcpResource.type === 'resource' &&
mcpResource.resource.mimeType === 'text/html'
) {
return (
<HtmlResource
resource={mcpResource.resource}
onGenericMcpAction={handleAction}
/>
);
}
return <p>Unsupported resource type.</p>;
};For more details and advanced usage, check out the docs and the HtmlResource component guide.
Ideas, feedback, and contributions are always welcome! See the contribution guidelines.
Licensed under the Apache License 2.0.
MCP UI is provided "as is" with no warranty. Use at your own risk.