📦 Model Context Protocol UI SDK

What's mcp-ui? • Installation • Quickstart • Core Concepts • Examples • Roadmap • Contributing • License

---

mcp-ui brings interactive web components to the Model Context Protocol (MCP). Deliver rich, dynamic UI resources directly from your MCP server to be rendered by the client. Take AI interaction to the next level!

This project is an experimental community playground for MCP UI ideas. Expect rapid iteration and enhancements!

mcpui-x.mp4

💡 What's mcp-ui?

mcp-ui is a TypeScript SDK comprising two packages:

• @mcp-ui/server: Utilities to generate HtmlResourceBlock objects 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.

North star -

• Enable servers to deliver rich, interactive UIs with ergonomic APIs
• Allow any host to support UI with its own look-and-feel
• Eliminate security concerns (limit/remove local code execution)

✨ Core Concepts

HtmlResource

The primary payload exchanged between the server and the client:

interface HtmlResourceBlock {
  type: 'resource';
  resource: {
    uri: string;       // ui://component/id
    mimeType: 'text/html' | 'text/uri-list'; // text/html for HTML content, text/uri-list for URL content
    text?: string;      // Inline HTML or external URL
    blob?: string;      // Base64-encoded HTML or URL
  };
}

• uri: Unique identifier for caching and routing
  • ui://… — UI resources (rendering method determined by mimeType)
• mimeType: text/html for HTML content (iframe srcDoc), text/uri-list for URL content (iframe src)
  • MCP-UI requires a single URL: While text/uri-list format supports multiple URLs, MCP-UI uses only the first valid URL and logs others
• text vs. blob: Choose text for simple strings; use blob for larger or encoded content.

It's rendered in the client with the <HtmlResource> React component. The component accepts the following props:

• resource: The resource object from an MCP message.
• onUiAction: A callback function to handle events from the resource.
• supportedContentTypes: (Optional) An array of content types to allow. Can include 'rawHtml' and/or 'externalUrl'. If omitted, all supported types are rendered. This is useful for restricting content types due to capability or security considerations.
• style: (Optional) Custom styles for the iframe.
• iframeProps: (Optional) Custom iframe props.

The HTML method is limited, and the external app method isn't secure enough for untrusted sites. We need a better method. We're exploring web components and remote-dom as alternatives that can allow the servers to render their components with the host's look-and-feel without local code execution.

UI Action

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.

🏗️ Installation

# using npm
npm install @mcp-ui/server @mcp-ui/client

# or pnpm
pnpm add @mcp-ui/server @mcp-ui/client

# or yarn
yarn add @mcp-ui/server @mcp-ui/client

🎬 Quickstart

1. Server-side: Build your resource blocks

   import { createHtmlResource } from '@mcp-ui/server';
   
   // Inline HTML
   const direct = createHtmlResource({
     uri: 'ui://greeting/1',
     content: { type: 'rawHtml', htmlString: '<p>Hello, MCP UI!</p>' },
     delivery: 'text',
   });
   
   // External URL
   const external = createHtmlResource({
     uri: 'ui://widget/session-42',
     content: { type: 'externalUrl', iframeUrl: 'https://example.com/widget' },
     delivery: 'text',
   });

2. 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.uri?.startsWith('ui://')
     ) {
       return (
         <HtmlResource
           resource={mcpResource.resource}
           supportedContentTypes={['rawHtml']}
           onUiAction={(result) => {
             console.log('Action:', result);
             return { status: 'ok' };
           }}
         />
       );
     }
     return <p>Unsupported resource</p>;
   }

3. Enjoy interactive MCP UIs — no extra configuration required.

🌍 Examples

Client example

• ui-inspector - inspect local mcp-ui-enabled servers. Check out the hosted version!
• MCP-UI Chat - interactive chat built with the mcp-ui client.

Server example Try out the hosted app -

• 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.

🛣️ Roadmap

• Add online playground
• Expand UI Action API (beyond tool calls)
• Add
• Support Web Components (in progress)
• Support Remote-DOM (in progress)
• Add component libraries (in progress)
• Support additional client-side libraries and render engines (e.g., Vue, TUI, etc.)

🤝 Contributing

Contributions, ideas, and bug reports are welcome! See the contribution guidelines to get started.

📄 License

Apache License 2.0 © The MCP UI Authors

Disclaimer

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.