build-mcp-ui

Build MCP UI (Expert)

Build production-grade MCP Apps with interactive UIs. This skill extends the basic create-mcp-app skill with battle-tested patterns for Cloudflare Workers deployment, two-tier tool architecture, cross-session state persistence, and proper build isolation.

Architecture Overview

An MCP App = Server-side tools + Bundled HTML resource + Client-side SDK.

Model calls tool → Server returns result + _meta.viewUUID
  → Host renders resource UI (iframe)
  → UI receives tool input/result via SDK callbacks
  → UI calls app-only tools via callServerTool()
  → UI updates model context via updateModelContext()/sendMessage()

Step 1: Decide Architecture

Deployment Target

Target	When to Use	Key Differences
Cloudflare Workers	Production, remote MCP, OAuth needed	Durable Objects, KV, R2; HTML imported as text module
Node.js (stdio)	Local dev, Claude Desktop only	tsx to run TS; simpler setup
Node.js (HTTP)	Remote without Cloudflare	Standard HTTP server; deploy anywhere

Framework

Framework	Import	Best For
React	@modelcontextprotocol/ext-apps/react	Rich UIs, component state, familiar DX
Vanilla JS	@modelcontextprotocol/ext-apps	Simple UIs, minimal bundle, full lifecycle control

Step 2: Project Structure

For Cloudflare Workers with React UI:

project/
├── src/                    # Worker code (NO DOM types)
│   ├── index.ts            # McpAgent Durable Object, fetch handler
│   ├── server.ts           # Tool & resource registration
│   └── env.d.ts            # Env interface extensions
├── app/                    # React UI (separate tsconfig with DOM libs)
│   ├── index.html          # Entry HTML template
│   ├── vite.config.ts      # Vite + singlefile plugin
│   ├── tsconfig.json       # DOM libs enabled
│   └── src/
│       ├── main.tsx         # React entry point
│       ├── App.tsx          # Main component with useApp hook
│       └── components/      # UI components
├── tsconfig.json           # Root config (EXCLUDES app/)
├── wrangler.jsonc           # Durable Objects, KV, rules
└── package.json

Critical: TypeScript isolation. Root tsconfig.json must exclude app/ to prevent DOM vs Worker type conflicts. The app/tsconfig.json includes DOM and DOM.Iterable libs.

Step 3: Single-File Bundling

The entire React app must bundle into a single HTML file for import as a text module.

app/vite.config.ts:

import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
import { viteSingleFile } from "vite-plugin-singlefile";

export default defineConfig({
  root: __dirname,
  plugins: [react(), tailwindcss(), viteSingleFile()],
  build: { outDir: "dist", emptyOutDir: true },
});

wrangler.jsonc — enable HTML text imports:

"rules": [{ "type": "Text", "globs": ["**/*.html"], "fallthrough": true }]

Import in server code:

import htmlContent from "../app/dist/index.html" with { type: "text" };

Step 4: Two-Tier Tool Pattern

This is the core architecture. Register two linked tools:

Model-Facing Tool (opens the UI)

• Visible to model, triggers UI display
• Returns _meta.viewUUID for state tracking
• Optionally returns existing session data
• Links to resource via _meta.ui.resourceUri

App-Only Tool (does the work)

• Hidden from model: visibility: ["app"]
• Called by UI via app.callServerTool()
• Performs the actual operation (API calls, storage, etc.)
• Returns structured data + content for the UI

See references/two-tier-tool-pattern.md for complete server-side code.

Step 5: Resource Registration

import { RESOURCE_MIME_TYPE, registerAppResource, registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import htmlContent from "../app/dist/index.html" with { type: "text" };

const RESOURCE_URI = "ui://my-app/mcp-app";

registerAppResource(
  server,
  "My App UI",
  RESOURCE_URI,
  { mimeType: RESOURCE_MIME_TYPE },
  async (uri) => ({
    contents: [{ uri: uri.href, mimeType: RESOURCE_MIME_TYPE, text: htmlContent }],
  }),
);

Step 6: Client-Side SDK Integration

React App

import { useApp, useDocumentTheme, useHostStyles } from "@modelcontextprotocol/ext-apps/react";

function App() {
  const { app, error } = useApp({ appInfo: { name: "MyApp", version: "1.0.0" }, capabilities: {} });
  useHostStyles(app, app?.getHostContext());
  const theme = useDocumentTheme();
  const isDark = theme === "dark";

  const handleAction = async () => {
    const result = await app.callServerTool({ name: "my-app-tool", arguments: { ... } });
    // Process result.content, result.structuredContent
  };
}

Vanilla JS — Lifecycle Callbacks

Register ALL handlers BEFORE app.connect():

const app = new App({ name: "MyApp", version: "1.0.0" });

app.ontoolinput = (params) => { /* Receive tool args from model */ };
app.ontoolresult = (result) => {
  // Receive tool result — extract viewUUID for state hydration
  if (result._meta?.viewUUID) {
    hydrateFromView(result._meta.viewUUID);
  }
};
app.onhostcontextchanged = (ctx) => { /* Apply theme, styles, safe areas */ };
app.onteardown = async () => ({});

await app.connect();

Step 7: viewUUID State Management

The viewUUID pattern enables cross-session image/data persistence:

1. Model-facing tool generates viewUUID = randomUUID() and returns it in _meta
2. App-only tool receives viewUUID as parameter, stores view:{viewUUID} → dataId in KV
3. UI receives viewUUID via ontoolresult, uses it to hydrate existing data
4. load tool looks up view:{viewUUID} to retrieve data across sessions

See references/viewuuid-state-pattern.md for the complete flow.

Step 8: UI-to-Model Communication

Two mechanisms for the UI to inform the model:

// Update model's context silently (no user message)
await app.updateModelContext({
  content: [{ type: "text", text: `Generated item with id "${itemId}"` }],
});

// Send a message as the user (triggers model response)
await app.sendMessage({
  role: "user",
  content: [{ type: "text", text: `Load item "${itemId}"` }],
});

Build Scripts

{
  "scripts": {
    "build:app": "vite build --config app/vite.config.ts",
    "dev:app": "vite build --config app/vite.config.ts --watch",
    "dev": "bun run build:app && concurrently --kill-others \"bun run dev:app\" \"wrangler dev\"",
    "deploy": "bun run build:app && wrangler deploy"
  }
}

Common Mistakes

1. Missing vite-plugin-singlefile — Without it, Vite outputs multiple files that cannot be imported as text
2. Shared tsconfig for worker and app — DOM types conflict with @cloudflare/workers-types
3. Handlers after connect() — Register ALL handlers BEFORE app.connect()
4. Missing resource registration — Both tool AND resource must be registered and linked via _meta.ui.resourceUri
5. No viewUUID in app-only tool — Pass viewUUID from UI to enable cross-session persistence
6. Forgetting visibility: ["app"] — App-only tools must be hidden from the model
7. No text fallback — Always include content array with text for non-UI hosts
8. Ignoring safe area insets — Always handle ctx.safeAreaInsets in onhostcontextchanged
9. Not building app before deploying — build:app must run before wrangler deploy
10. Hardcoded styles — Use host CSS variables (var(--color-background-*), var(--color-text-*)) for theme integration

Additional Resources

Reference Files

• references/two-tier-tool-pattern.md — Complete server-side tool registration with model-facing and app-only tools
• references/viewuuid-state-pattern.md — Full viewUUID lifecycle for cross-session data persistence
• references/cloudflare-workers-setup.md — Wrangler config, Durable Objects, KV, R2, environment types
• references/react-app-template.md — Complete React app template with all hooks and components

SDK Reference

Clone for API docs and examples:

git clone --branch "v$(npm view @modelcontextprotocol/ext-apps version)" --depth 1 https://github.com/modelcontextprotocol/ext-apps.git /tmp/mcp-ext-apps