OpenAI

xmcp is compatible with MCP UI, which can be used to build interactive interfaces for your MCP server.

Installation

In your current xmcp project, install the following dependency:

pnpm i @mcp-ui/server

You can create a UI resource for your MCP server using the createUIResource function. It allows you to define UI snippets on the server-side, which can then be seamlessly and securely rendered on the client.

Direct HTML (Text Encoding)

Direct HTML content delivered as plain text:

import { createUIResource } from "@mcp-ui/server";

const resource = createUIResource({
  uri: "ui://my-component/instance-1",
  content: { type: "rawHtml", htmlString: "<p>Hello World</p>" },
  encoding: "text",
});

Output:

{
  "type": "resource",
  "resource": {
    "uri": "ui://my-component/instance-1",
    "mimeType": "text/html",
    "text": "<p>Hello World</p>"
  }
}

Direct HTML (Base64 Blob)

Direct HTML content delivered as a Base64-encoded blob:

const resource = createUIResource({
  uri: "ui://my-component/instance-2",
  content: { type: "rawHtml", htmlString: "<h1>Complex HTML</h1>" },
  encoding: "blob",
});

Output:

{
  "type": "resource",
  "resource": {
    "uri": "ui://my-component/instance-2",
    "mimeType": "text/html",
    "blob": "PGgxPkNvbXBsZXggSFRNTDwvaDE+"
  }
}

External URL (Text Encoding)

External URL delivered as plain text for iframe embedding:

const dashboardUrl = "https://my.analytics.com/dashboard/123";

const resource = createUIResource({
  uri: "ui://analytics-dashboard/main",
  content: { type: "externalUrl", iframeUrl: dashboardUrl },
  encoding: "text",
});

Output:

{
  "type": "resource",
  "resource": {
    "uri": "ui://analytics-dashboard/main",
    "mimeType": "text/uri-list",
    "text": "https://my.analytics.com/dashboard/123"
  }
}

External URL (Blob Encoding)

External URL delivered as a Base64-encoded blob:

const chartApiUrl = "https://charts.example.com/api?type=pie&data=1,2,3";

const resource = createUIResource({
  uri: "ui://live-chart/session-xyz",
  content: { type: "externalUrl", iframeUrl: chartApiUrl },
  encoding: "blob",
});

Output:

{
  "type": "resource",
  "resource": {
    "uri": "ui://live-chart/session-xyz",
    "mimeType": "text/uri-list",
    "blob": "aHR0cHM6Ly9jaGFydHMuZXhhbXBsZS5jb20vYXBpP3R5cGU9cGllJmRhdGE9MSwyLDM="
  }
}

Remote DOM Script

Remote DOM script for building interactive components:

const remoteDomScript = `
  const button = document.createElement('ui-button');
  button.setAttribute('label', 'Click me for a tool call!');
  button.addEventListener('press', () => {
    window.parent.postMessage({ 
      type: 'tool', 
      payload: { 
        toolName: 'uiInteraction', 
        params: { action: 'button-click', from: 'remote-dom' } 
      } 
    }, '*');
  });
  root.appendChild(button);
`;

const resource = createUIResource({
  uri: "ui://remote-component/action-button",
  content: {
    type: "remoteDom",
    script: remoteDomScript,
    framework: "react", // or 'webcomponents'
  },
  encoding: "text",
});

Output:

{
  "type": "resource",
  "resource": {
    "uri": "ui://remote-component/action-button",
    "mimeType": "application/vnd.mcp-ui.remote-dom+javascript; framework=react",
    "text": "\\n  const button = document.createElement('ui-button');\\n  button.setAttribute('label', 'Click me for a tool call!');\\n  button.addEventListener('press', () => {\\n    window.parent.postMessage({ type: 'tool', payload: { toolName: 'uiInteraction', params: { action: 'button-click', from: 'remote-dom' } } }, '*');\\n  });\\n  root.appendChild(button);\\n"
  }
}

Usage

UI resources are served through tools in your MCP server. This works with both standalone applications and projects where xmcp is integrated, like Next.js or Express.

In xmcp, simply return the UI resource in your tool's content array:

src/tools/get-ui.ts

import { type ToolMetadata } from "xmcp";
import { uiResource } from "@/lib/ui";

// ...schema and metadata

export default function getUI() {
  return {
    content: [uiResource],
  };
}

MCP UI

Installation

Create a UI resource

Direct HTML (Text Encoding)

Direct HTML (Base64 Blob)

External URL (Text Encoding)

External URL (Blob Encoding)

Remote DOM Script

Usage

One framework to rule them all