jake/clawdbot-workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
clawdbot-workspace/skills/mcp-apps-merged/SKILL.md

39 KiB
Raw Permalink Blame History

name description
Create MCP App This skill should be used when the user asks to "create an MCP App", "add a UI to an MCP tool", "build an interactive MCP View", "scaffold an MCP App", or needs guidance on MCP Apps SDK patterns, UI-resource registration, MCP App lifecycle, host integration, streaming input, fullscreen mode, or interactive UI patterns. The definitive guide for building MCP Apps with interactive UIs.

MCP Apps Complete Guide

Purpose: The definitive guide to building MCP Apps correctly. Invoke with /mcp-apps when working on MCP Apps. This merges official SDK documentation with battle-tested patterns from real-world debugging.

What MCP Apps Actually Are

The Core Concept

MCP Apps is an official extension to the Model Context Protocol (SEP-1865) that allows MCP servers to deliver interactive HTML user interfaces that render inside AI chat windows (Claude Desktop, Goose, etc.).

Key Distinction:

  • MCP Apps = Official standard from @modelcontextprotocol/ext-apps (USE THIS)
  • MCP-UI = Older community library from @mcp-ui/server (DEPRECATED - avoid)

The Fundamental Pattern

MCP App = Tool Definition + UI Resource + Proper Response

Three things MUST be linked:

  1. Tool Definition with _meta.ui.resourceUri
  2. UI Resource registered with text/html;profile=mcp-app MIME type
  3. Tool Response that triggers the host to fetch and render the UI

How The Data Flows

1. Server starts, registers tools with _meta.ui.resourceUri
2. Server registers UI resources via resources/list
3. Host (Goose/Claude) calls tools/list, sees _meta.ui.resourceUri
4. User triggers tool call
5. Server executes tool, returns content + structuredContent
6. Host sees tool has UI, fetches resource via resources/read
7. Host renders HTML in sandboxed iframe
8. UI calls app.connect(), receives tool result via ontoolresult
9. UI renders the data

Quick Reference: The Pattern

MCP App = Tool + UI Resource + Link
  1. Tool - Called by LLM/host, returns data with structuredContent
  2. Resource - Serves bundled HTML (single file via vite-plugin-singlefile)
  3. Link - Tool's _meta.ui.resourceUri points to the resource URI
Host calls tool → Server returns result → Host fetches resource → UI receives result via ontoolresult

Quick Start Decision Tree

Framework Selection

Framework SDK Support Best For
React useApp hook provided Teams familiar with React
Vanilla JS Manual lifecycle Simple apps, no build complexity
Vue Manual lifecycle Vue teams (template available)
Svelte Manual lifecycle Svelte teams (template available)
Preact Manual lifecycle Lightweight React alternative
Solid Manual lifecycle Solid teams (template available)

Project Context

Adding to existing MCP server:

  • Import registerAppTool, registerAppResource from SDK
  • Add tool registration with _meta.ui.resourceUri
  • Add resource registration serving bundled HTML

Creating new MCP server:

  • Set up server with transport (stdio or HTTP)
  • Register tools and resources
  • Configure build system with vite-plugin-singlefile

Required Packages

npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk zod
npm install -D typescript vite vite-plugin-singlefile tsx

CRITICAL: Use npm install to add dependencies rather than manually writing version numbers. This lets npm resolve the latest compatible versions. Never specify version numbers from memory.

Package Purpose REQUIRED
@modelcontextprotocol/ext-apps Official MCP Apps SDK (server + client) YES
@modelcontextprotocol/sdk Base MCP SDK with McpServer class YES
zod Schema validation for tool parameters YES
vite + vite-plugin-singlefile Bundle UI to single HTML file YES
tsx Run TypeScript server files YES

Do NOT use: @mcp-ui/server (deprecated, different API)

Note

: The SDK examples use bun but generated projects should use tsx for broader compatibility.

Project Structure

my-mcp-app/
├── package.json
├── tsconfig.json
├── src/
│   ├── server.ts              # MCP server with tools + resources
│   └── app-ui/
│       ├── mcp-app.html       # UI HTML template
│       ├── src/
│       │   └── mcp-app.ts     # UI logic
│       └── vite.config.ts     # Bundles to single file
└── dist/
    ├── server.js              # Compiled server
    └── app-ui/
        └── mcp-app.html       # Bundled single-file UI

Get Reference Code

Clone the SDK repository for working examples and API documentation:

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

Framework Templates

Learn and adapt from /tmp/mcp-ext-apps/examples/basic-server-{framework}/:

Template Key Files
basic-server-vanillajs/ server.ts, src/mcp-app.ts, mcp-app.html
basic-server-react/ server.ts, src/mcp-app.tsx (uses useApp hook)
basic-server-vue/ server.ts, src/App.vue
basic-server-svelte/ server.ts, src/App.svelte
basic-server-preact/ server.ts, src/mcp-app.tsx
basic-server-solid/ server.ts, src/mcp-app.tsx

Each template includes:

  • Complete server.ts with registerAppTool and registerAppResource
  • Client-side app with all lifecycle handlers
  • vite.config.ts with vite-plugin-singlefile
  • package.json with all required dependencies
  • .gitignore excluding node_modules/ and dist/

API Reference (Source Files)

Read JSDoc documentation directly from /tmp/mcp-ext-apps/src/:

File Contents
src/app.ts App class, handlers (ontoolinput, ontoolresult, onhostcontextchanged, onteardown), lifecycle
src/server/index.ts registerAppTool, registerAppResource, tool visibility options
src/spec.types.ts All type definitions: McpUiHostContext, CSS variable keys, display modes
src/styles.ts applyDocumentTheme, applyHostStyleVariables, applyHostFonts
src/react/useApp.tsx useApp hook for React apps
src/react/useHostStyles.ts useHostStyles, useHostStyleVariables, useHostFonts hooks

Advanced Examples

Example Pattern Demonstrated
examples/shadertoy-server/ Streaming partial input + visibility-based pause/play (best practice for large inputs)
examples/wiki-explorer-server/ callServerTool for interactive data fetching
examples/system-monitor-server/ Polling pattern with interval management
examples/video-resource-server/ Binary/blob resources
examples/sheet-music-server/ ontoolinput - processing tool args before execution completes
examples/threejs-server/ ontoolinputpartial - streaming/progressive rendering
examples/map-server/ updateModelContext - keeping model informed of UI state
examples/transcript-server/ updateModelContext + sendMessage - background context updates + user-initiated messages
examples/basic-host/ Reference host implementation using AppBridge

Server-Side Implementation

Critical Imports

import {
  registerAppTool,
  registerAppResource,
  RESOURCE_MIME_TYPE,  // = "text/html;profile=mcp-app"
} from "@modelcontextprotocol/ext-apps/server";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

Complete Server Template

import {
  registerAppTool,
  registerAppResource,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import * as fs from "node:fs/promises";
import * as path from "node:path";

// Path to bundled UI (after vite build)
const DIST_DIR = path.join(__dirname, "app-ui");

export function createServer(): McpServer {
  const server = new McpServer({
    name: "my-mcp-app",
    version: "1.0.0",
  });

  // CRITICAL: Define the resource URI (must use ui:// scheme)
  const widgetResourceUri = "ui://my-app/widget.html";

  // ============================================
  // STEP 1: Register Tool with UI Metadata
  // ============================================
  registerAppTool(
    server,
    "my_tool",  // Tool name (snake_case recommended)
    {
      title: "My Tool",  // Human-readable title
      description: "Description for the LLM to understand when to use this",
      inputSchema: {
        // Use Zod schemas for parameters
        param1: z.string().describe("Parameter description"),
        param2: z.number().optional().describe("Optional number"),
      },
      // CRITICAL: This links tool to UI resource
      _meta: {
        ui: { resourceUri: widgetResourceUri },
      },
    },
    async (args: { param1: string; param2?: number }) => {
      // Your tool logic here
      const result = {
        data: args.param1,
        timestamp: new Date().toISOString(),
      };

      // CRITICAL: Return format
      return {
        // Text fallback for non-UI hosts
        content: [
          {
            type: "text" as const,
            text: `Result: ${JSON.stringify(result)}`,
          },
        ],
        // Structured data passed to UI via ontoolresult
        structuredContent: result,
      };
    }
  );

  // ============================================
  // STEP 2: Register UI Resource
  // ============================================
  registerAppResource(
    server as any,  // Type cast needed due to SDK types
    widgetResourceUri,  // Resource name
    widgetResourceUri,  // Resource URI (same as name for simplicity)
    { mimeType: RESOURCE_MIME_TYPE },  // CRITICAL: Use this constant
    async () => {
      console.error(`[MCP App] Reading UI resource`);
      try {
        const html = await fs.readFile(
          path.join(DIST_DIR, "mcp-app.html"),
          "utf-8"
        );
        console.error(`[MCP App] UI loaded (${html.length} bytes)`);
        return {
          contents: [
            {
              uri: widgetResourceUri,
              mimeType: RESOURCE_MIME_TYPE,
              text: html,
            },
          ],
        };
      } catch (error) {
        console.error(`[MCP App] Failed to read UI:`, error);
        return {
          contents: [
            {
              uri: widgetResourceUri,
              mimeType: RESOURCE_MIME_TYPE,
              text: "<html><body>UI not built</body></html>",
            },
          ],
        };
      }
    }
  );

  // Add more tools (with or without UI)
  server.tool(
    "helper_tool",
    "A helper tool without UI",
    {
      input: z.string().describe("Input value"),
    },
    async (args) => {
      return {
        content: [{ type: "text" as const, text: `Got: ${args.input}` }],
      };
    }
  );

  return server;
}

// Entry point
async function main() {
  const server = createServer();
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP App Server started");
}

main().catch((e) => {
  console.error(`Error: ${e.message}`);
  process.exit(1);
});

Tool Registration (Quick Reference)

const resourceUri = "ui://my-app/widget.html";

registerAppTool(
  server,
  "tool_name",
  {
    title: "Tool Title",
    description: "Description for LLM",
    inputSchema: {
      param: z.string().describe("Parameter description"),
    },
    _meta: {
      ui: { resourceUri },
    },
  },
  async (args) => {
    const result = { data: args.param };
    return {
      content: [{ type: "text" as const, text: JSON.stringify(result) }],
      structuredContent: result,  // This goes to UI
    };
  }
);

Resource Registration

registerAppResource(
  server as any,
  resourceUri,
  resourceUri,
  { mimeType: RESOURCE_MIME_TYPE },
  async () => ({
    contents: [{
      uri: resourceUri,
      mimeType: RESOURCE_MIME_TYPE,
      text: await fs.readFile(path.join(__dirname, "app-ui/mcp-app.html"), "utf-8"),
    }],
  })
);

Tool Visibility Options

// Default: visible to both model and app
_meta: { ui: { resourceUri, visibility: ["model", "app"] } }

// UI-only (hidden from model) - for refresh buttons, form submissions, internal actions
_meta: { ui: { resourceUri, visibility: ["app"] } }

// Model-only (app cannot call)
_meta: { ui: { resourceUri, visibility: ["model"] } }

Server-Side Action Tools

For interactive UIs, add action tools that the UI calls via callServerTool:

// View tool (returns UI) - called by model
registerAppTool(server, "view_board", { /* ... */ }, async (args) => {
  const data = await getData();
  return {
    content: [{ type: "text", text: `Board loaded` }],
    structuredContent: data
  };
});

// Action tool (no UI) - called by UI via callServerTool
{
  name: 'update_item',
  description: 'Update an item (used by UI for drag-drop/edit)',
  inputSchema: {
    type: 'object',
    properties: {
      itemId: { type: 'string' },
      columnId: { type: 'string' },
      name: { type: 'string' },
      value: { type: 'number' }
    },
    required: ['itemId']
  }
  // No _meta.ui - this is not a view tool
}

// Handler in executeTool:
case 'update_item':
  const result = await apiClient.updateItem(args.itemId, args);
  return {
    content: [{ type: 'text', text: `Updated ${result.name}` }],
    structuredContent: { success: true, item: result }
  };

Client-Side Implementation

Complete HTML Template (src/app-ui/mcp-app.html)

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>My MCP App</title>
  <style>
    /* All styles inline - will be bundled */
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      padding: 16px;
      background: #f5f5f5;
    }
    .loading { text-align: center; color: #666; padding: 20px; }
    .error { color: #dc2626; background: #fef2f2; padding: 16px; border-radius: 8px; }
    .content { background: white; padding: 16px; border-radius: 8px; }
  </style>
</head>
<body>
  <div id="app">
    <div class="loading">Loading...</div>
  </div>
  <script type="module" src="/src/mcp-app.ts"></script>
</body>
</html>

Complete UI Logic (src/app-ui/src/mcp-app.ts)

import { App } from "@modelcontextprotocol/ext-apps";

// Define your data types
interface MyData {
  data: string;
  timestamp: string;
}

const appEl = document.getElementById("app")!;

// Create app instance
const app = new App({
  name: "My MCP App",
  version: "1.0.0"
});

// ============================================
// CRITICAL: Set handlers BEFORE connect()
// ============================================
app.ontoolresult = (result) => {
  console.log("Tool result received:", result);

  try {
    // Get data from structuredContent (preferred) or parse text
    let data: MyData;

    if (result.structuredContent) {
      data = result.structuredContent as MyData;
    } else {
      const textContent = result.content?.find((c) => c.type === "text")?.text;
      if (textContent) {
        data = JSON.parse(textContent);
      } else {
        throw new Error("No data in result");
      }
    }

    renderContent(data);
  } catch (error) {
    console.error("Failed to parse result:", error);
    appEl.innerHTML = `<div class="error">Failed to load: ${error}</div>`;
  }
};

app.onerror = (error) => {
  console.error("App error:", error);
  appEl.innerHTML = `<div class="error">Error: ${error.message}</div>`;
};

// ============================================
// CRITICAL: Connect to host (must be called)
// ============================================
app.connect();

// Render function
function renderContent(data: MyData) {
  appEl.innerHTML = `
    <div class="content">
      <h2>Result</h2>
      <p><strong>Data:</strong> ${escapeHtml(data.data)}</p>
      <p><strong>Time:</strong> ${data.timestamp}</p>
      <button id="refresh">Refresh</button>
    </div>
  `;

  // Add interactivity
  document.getElementById("refresh")?.addEventListener("click", async () => {
    try {
      const result = await app.callServerTool({
        name: "my_tool",
        arguments: { param1: "refreshed" }
      });
      const newData = result.structuredContent as MyData;
      renderContent(newData);
    } catch (error) {
      console.error("Refresh failed:", error);
    }
  });
}

// Helper to prevent XSS
function escapeHtml(text: string): string {
  const div = document.createElement('div');
  div.textContent = text;
  return div.innerHTML;
}

Vanilla JS Pattern (Full Lifecycle)

import { App } from "@modelcontextprotocol/ext-apps";
import { applyDocumentTheme, applyHostStyleVariables, applyHostFonts } from "@modelcontextprotocol/ext-apps";

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

// CRITICAL: Set ALL handlers BEFORE connect()
app.ontoolinput = (params) => {
  // Tool args available immediately (before execution completes)
  console.log("Input:", params.arguments);
};

app.ontoolinputpartial = (params) => {
  // Streaming partial input (healed JSON, always valid)
  console.log("Partial:", params.arguments);
};

app.ontoolresult = (result) => {
  // Tool execution complete - render the data
  const data = result.structuredContent;
  renderUI(data);
};

app.onhostcontextchanged = (ctx) => {
  // Theme/style updates from host
  if (ctx.theme) applyDocumentTheme(ctx.theme);
  if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
  if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
  // Handle safe area insets
  if (ctx.safeAreaInsets) {
    const { top, right, bottom, left } = ctx.safeAreaInsets;
    document.body.style.padding = `${top}px ${right}px ${bottom}px ${left}px`;
  }
};

app.onteardown = async () => {
  // Cleanup before UI closes
  return {};
};

app.onerror = (error) => {
  console.error("App error:", error);
};

// THEN connect
await app.connect();

React Pattern

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

function MyApp() {
  const [data, setData] = useState(null);

  const { app } = useApp({
    appInfo: { name: "My App", version: "1.0.0" },
    onToolResult: (result) => setData(result.structuredContent),
  });

  useHostStyles(app);  // Injects CSS variables, making var(--*) available

  return <div>{data && <Content data={data} />}</div>;
}

Calling Server Tools from UI

const result = await app.callServerTool({
  name: "tool_name",
  arguments: { param: "value" }
});
const newData = result.structuredContent;

Updating Model Context

// Keep the model informed of UI state changes
app.updateModelContext({
  summary: "User selected 3 items",
  details: { selectedIds: [1, 2, 3] }
});

Debug Logging to Host

// Send debug logs to the host application (not just iframe dev console)
await app.sendLog({ level: "info", data: "Debug message" });
await app.sendLog({ level: "error", data: { error: err.message } });

App Lifecycle Handlers

Handler When It Fires Use For
ontoolinput Tool args available (before execution) Show loading state, preview
ontoolinputpartial Streaming partial input (healed JSON) Progressive rendering during generation
ontoolresult Tool execution complete Render main UI
onhostcontextchanged Theme/style/locale/display mode changes Apply host styling, safe areas, fullscreen
onteardown UI closing Cleanup, save state
onerror Error occurred Error display

Streaming Partial Input

For large tool inputs, use ontoolinputpartial to show progress during LLM generation. The partial JSON is healed (always valid), enabling progressive UI updates.

Spec: ui/notifications/tool-input-partial

app.ontoolinputpartial = (params) => {
  const args = params.arguments; // Healed partial JSON - always valid, fields appear as generated
  // Use args directly for progressive rendering
};

app.ontoolinput = (params) => {
  // Final complete input - switch from preview to full render
};

Streaming Use Cases

Pattern Example
Code preview Show streaming code in <pre>, render on complete (examples/shadertoy-server/)
Progressive form Fill form fields as they stream in
Live chart Add data points to chart as array grows
Partial render Render incomplete structured data (tables, lists, trees)

Simple Streaming Pattern (Code Preview)

app.ontoolinputpartial = (params) => {
  codePreview.textContent = params.arguments?.code ?? "";
  codePreview.style.display = "block";
  canvas.style.display = "none";
};
app.ontoolinput = (params) => {
  codePreview.style.display = "none";
  canvas.style.display = "block";
  render(params.arguments);
};

Visibility-Based Resource Management

Pause expensive operations (animations, WebGL, polling) when view scrolls out of viewport:

const observer = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    if (entry.isIntersecting) {
      animation.play(); // or: startPolling(), shaderToy.play()
    } else {
      animation.pause(); // or: stopPolling(), shaderToy.pause()
    }
  });
});
observer.observe(document.querySelector(".main"));

See examples/shadertoy-server/ for a real implementation combining streaming input + visibility pause.

Fullscreen Mode

Request fullscreen via app.requestDisplayMode(). Check availability in host context:

let currentMode: "inline" | "fullscreen" = "inline";

app.onhostcontextchanged = (ctx) => {
  // Check if fullscreen available
  if (ctx.availableDisplayModes?.includes("fullscreen")) {
    fullscreenBtn.style.display = "block";
  }
  // Track current mode
  if (ctx.displayMode) {
    currentMode = ctx.displayMode;
    container.classList.toggle("fullscreen", currentMode === "fullscreen");
  }
};

async function toggleFullscreen() {
  const newMode = currentMode === "fullscreen" ? "inline" : "fullscreen";
  const result = await app.requestDisplayMode({ mode: newMode });
  currentMode = result.mode;
}

CSS for Fullscreen — Remove border radius in fullscreen:

.main { border-radius: var(--border-radius-lg); overflow: hidden; }
.main.fullscreen { border-radius: 0; }

See examples/shadertoy-server/ for complete implementation.

Safe Area Insets

Always respect safeAreaInsets to avoid content being clipped by host chrome:

app.onhostcontextchanged = (ctx) => {
  if (ctx.safeAreaInsets) {
    const { top, right, bottom, left } = ctx.safeAreaInsets;
    document.body.style.padding = `${top}px ${right}px ${bottom}px ${left}px`;
  }
};

Host CSS Variables

Applying Styles

Vanilla JS - Use helper functions:

import { applyDocumentTheme, applyHostStyleVariables, applyHostFonts } from "@modelcontextprotocol/ext-apps";

app.onhostcontextchanged = (ctx) => {
  if (ctx.theme) applyDocumentTheme(ctx.theme);
  if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
  if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
};

React - Use hooks:

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

const { app } = useApp({ appInfo, capabilities, onAppCreated });
useHostStyles(app); // Injects CSS variables to document, making var(--*) available

Using Variables in CSS

After applying with applyHostStyleVariables() or useHostStyles():

.container {
  background: var(--color-background-secondary);
  color: var(--color-text-primary);
  font-family: var(--font-sans);
  border-radius: var(--border-radius-md);
}
.code {
  font-family: var(--font-mono);
  font-size: var(--font-text-sm-size);
  line-height: var(--font-text-sm-line-height);
  color: var(--color-text-secondary);
}
.heading {
  font-size: var(--font-heading-lg-size);
  font-weight: var(--font-weight-semibold);
}

Key variable groups: --color-background-*, --color-text-*, --color-border-*, --font-sans, --font-mono, --font-text-*-size, --font-heading-*-size, --border-radius-*. See src/spec.types.ts for full list.

Build Configuration

Vite Config (src/app-ui/vite.config.ts)

import { defineConfig } from "vite";
import { viteSingleFile } from "vite-plugin-singlefile";

export default defineConfig({
  plugins: [viteSingleFile()],  // CRITICAL: Bundles everything into one HTML
  root: __dirname,
  build: {
    outDir: "../../dist/app-ui",
    emptyOutDir: true,
    rollupOptions: { input: "mcp-app.html" },
  },
});

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "src/app-ui/**/*"]
}

CRITICAL: Exclude src/app-ui/**/* from TypeScript - Vite handles that separately.

package.json Scripts

{
  "type": "module",
  "scripts": {
    "build:ui": "cd src/app-ui && npx vite build",
    "build:server": "tsc",
    "build": "npm run build:ui && npm run build:server",
    "serve": "tsx src/server.ts",
    "start": "node dist/server.js"
  }
}

Interactive UI Patterns

CRITICAL: Module Scope Issue

When using <script type="module">, all variables are module-scoped and NOT accessible from:

  • External <script> tags
  • HTML attributes (onclick, onsubmit, ondblclick)

Solution 1: Keep everything in the module

// Inside the module script - works because app and functions are in scope
function renderUI(data) {
  // Render UI
  renderHTML(data);
  // Store data globally for interactive features
  window._appData = data;
  // Setup interactivity after render
  setupInteractivity();
}

function setupInteractivity() {
  document.querySelectorAll('.card').forEach(card => {
    card.draggable = true;
    card.ondragstart = (e) => { /* has access to module's app variable */ };
    card.ondblclick = () => openEditModal(card.dataset.id);
  });
}

Solution 2: Expose to window (for HTML attributes)

// At end of module, expose functions needed by HTML onclick/onsubmit
window.openEditModal = function(id) { /* ... */ };
window.closeEditModal = function() { /* ... */ };
window.saveItem = async function(e) {
  e.preventDefault();
  await app.callServerTool({ name: 'update_item', arguments: { id, data } });
};

Drag-and-Drop Pattern

// Store current data globally for access during drag/drop
window._appData = null;

function setupDragDrop() {
  let draggedId = null;

  // Make cards draggable
  document.querySelectorAll('.card').forEach(card => {
    card.draggable = true;

    card.ondragstart = (e) => {
      draggedId = card.dataset.id;
      card.classList.add('dragging');
      e.dataTransfer.effectAllowed = 'move';
    };

    card.ondragend = () => {
      card.classList.remove('dragging');
      document.querySelectorAll('.column').forEach(c => c.classList.remove('drag-over'));
    };
  });

  // Setup drop zones
  document.querySelectorAll('.column').forEach(col => {
    col.ondragover = (e) => {
      e.preventDefault();
      col.classList.add('drag-over');
    };

    col.ondragleave = (e) => {
      if (!col.contains(e.relatedTarget)) col.classList.remove('drag-over');
    };

    col.ondrop = async (e) => {
      e.preventDefault();
      col.classList.remove('drag-over');
      if (!draggedId) return;

      const newColumnId = col.dataset.columnId;

      // Call server to persist the move
      try {
        await app.callServerTool({
          name: 'update_item',
          arguments: { itemId: draggedId, columnId: newColumnId }
        });

        // Update local data and re-render
        const item = window._appData.items.find(i => i.id === draggedId);
        if (item) {
          item.columnId = newColumnId;
          renderUI(window._appData);  // Re-render (which calls setupDragDrop again)
        }
      } catch (err) {
        alert('Move failed: ' + err.message);
      }

      draggedId = null;
    };
  });
}

Edit Modal Pattern

HTML Structure:

<div id="editModal" class="modal-overlay" style="display:none;">
  <div class="modal-content">
    <div class="modal-header">
      <h3>Edit Item</h3>
      <button onclick="closeEditModal()">&times;</button>
    </div>
    <form onsubmit="saveItem(event)">
      <input type="hidden" id="editItemId">
      <div class="form-group">
        <label>Name</label>
        <input type="text" id="editName" required>
      </div>
      <div class="form-group">
        <label>Value</label>
        <input type="number" id="editValue">
      </div>
      <button type="submit">Save</button>
    </form>
  </div>
</div>

JavaScript (in module, exposed to window):

window.openEditModal = function(id) {
  const item = window._appData?.items?.find(i => i.id === id);
  if (!item) return;

  document.getElementById('editItemId').value = id;
  document.getElementById('editName').value = item.name || '';
  document.getElementById('editValue').value = item.value || 0;
  document.getElementById('editModal').style.display = 'flex';
};

window.closeEditModal = function() {
  document.getElementById('editModal').style.display = 'none';
};

window.saveItem = async function(e) {
  e.preventDefault();
  const id = document.getElementById('editItemId').value;
  const name = document.getElementById('editName').value;
  const value = parseFloat(document.getElementById('editValue').value) || 0;

  try {
    await app.callServerTool({
      name: 'update_item',
      arguments: { itemId: id, name, value }
    });

    // Update local data and re-render
    const item = window._appData?.items?.find(i => i.id === id);
    if (item) {
      item.name = name;
      item.value = value;
      renderUI(window._appData);
    }
    closeEditModal();
  } catch (err) {
    alert('Save failed: ' + err.message);
  }
};

CSS for Drag-and-Drop & Modals

.card {
  cursor: grab;
  transition: transform 0.2s, opacity 0.2s;
}

.card:active {
  cursor: grabbing;
}

.card.dragging {
  opacity: 0.5;
  transform: rotate(2deg);
}

.column.drag-over .cards-container {
  background: #e0e7ff;
  border: 2px dashed #4f46e5;
}

.modal-overlay {
  position: fixed;
  inset: 0;
  background: rgba(0,0,0,0.5);
  display: flex;
  align-items: center;
  justify-content: center;
  z-index: 1000;
}

.modal-content {
  background: white;
  padding: 24px;
  border-radius: 8px;
  min-width: 300px;
}

Key Lessons Learned

  1. Module scope: <script type="module"> creates isolated scope - use window.fn = fn for HTML attribute access
  2. Re-render after changes: Store data in window._appData, update it, call render function again
  3. Setup handlers after render: Call setupDragDrop() at end of render function since DOM changes
  4. Use dataset attributes: card.dataset.id maps to data-id="..." in HTML
  5. Column identification: Add data-column-id or data-stage-id to drop zone containers
  6. Action vs View tools: View tools have _meta.ui.resourceUri, action tools don't

Data Handling Gotchas

Array Data Must Be Validated

// BAD - crashes if data.items isn't an array
const html = data.items.map(item => `<li>${item}</li>`).join('');

// GOOD - defensive coding
let items: Item[] = [];
if (Array.isArray(data.items)) {
  items = data.items;
} else if (data.items && typeof data.items === 'object') {
  // Handle nested { items: [...] } format
  const nested = (data.items as any).items;
  if (Array.isArray(nested)) items = nested;
}
const html = items.map(item => `<li>${item}</li>`).join('');

Always Escape User Content

function escapeHtml(text: string): string {
  const div = document.createElement('div');
  div.textContent = text;
  return div.innerHTML;
}

Critical Rules

MUST DO

Requirement Why It Matters
Use McpServer class Low-level Server class doesn't work with helpers
Use registerAppTool Properly sets up _meta.ui.resourceUri in both formats
Use registerAppResource Registers resource with correct MIME type
Use RESOURCE_MIME_TYPE constant Must be exactly text/html;profile=mcp-app
Use ui:// scheme for URIs Required by spec
Bundle UI to SINGLE HTML file Host expects one file, use vite-plugin-singlefile
Set ALL handlers BEFORE app.connect() Miss initial data otherwise
Call app.connect() UI won't communicate without it
Return structuredContent in tool response This is how UI receives typed data
Return text content as fallback Non-UI hosts need this
Use Zod schemas for tool params McpServer requires Zod, not plain objects
Exclude app-ui from tsconfig Vite compiles UI separately
Handle safeAreaInsets Avoid content clipped by host chrome
Use npm install for dependencies Never hardcode version numbers from memory
Use host CSS variables Theme integration, don't hardcode colors
Use ontoolinputpartial for large inputs Show progress during LLM generation

MUST NOT

Anti-Pattern What Happens
Using Server instead of McpServer registerAppTool won't work
Using @mcp-ui/server Different API, deprecated
Plain object inputSchema TypeScript errors, runtime failures
Multiple JS/CSS files in UI Host can't load them
Setting handlers after connect() Miss the initial tool result
Forgetting _meta.ui.resourceUri Host won't fetch UI
Wrong MIME type Host ignores resource
import.meta.url in CommonJS Build errors
Returning _meta in tool response Not needed if tool definition has it
Hardcoded styles instead of CSS vars Breaks host theme integration
Ignoring safe area insets Content clipped on some hosts
Manually writing dependency versions Version mismatches, use npm install

Host-Specific Notes

Goose

  • Minimum version: 1.19.0 for MCP Apps
  • Works in: Goose Desktop, Goose Web (goose web), Goose CLI
  • Config location: ~/.config/goose/config.yaml
  • Enable alpha features: Add ALPHA_FEATURES: true to config
  • Logs: Server stderr goes to Goose logs

Claude Desktop

  • Config location: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Node path: Use full path like /opt/homebrew/opt/node@22/bin/node
  • Logs: Check Claude Desktop developer console

Testing

Quick Pipe Tests (JSONRPC)

# Test tools/list - verify _meta.ui.resourceUri present
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/server.js

# Test resources/list - verify MIME type correct
echo '{"jsonrpc":"2.0","id":1,"method":"resources/list","params":{}}' | node dist/server.js

# Test resources/read - verify HTML returned
echo '{"jsonrpc":"2.0","id":1,"method":"resources/read","params":{"uri":"ui://my-app/widget.html"}}' | node dist/server.js

Using basic-host (Interactive Testing)

Test MCP Apps locally with the basic-host example from the SDK repo:

# Terminal 1: Build and run your server
npm run build && npm run serve

# Terminal 2: Run basic-host (from cloned repo)
cd /tmp/mcp-ext-apps/examples/basic-host
npm install
SERVERS='["http://localhost:3001/mcp"]' npm run start
# Open http://localhost:8080

Configure SERVERS with a JSON array of your server URLs (default: http://localhost:3001/mcp).

Debugging Checklist

When UI doesn't render:

  1. Check tools/list - Does tool have _meta.ui.resourceUri?
  2. Check resources/list - Is resource listed with correct MIME type?
  3. Check resources/read - Does it return HTML content?
  4. Check browser console - Any JS errors in the iframe?
  5. Check server stderr - Is resource being fetched?
  6. Verify build - Is dist/app-ui/mcp-app.html a single file with inlined JS?
  7. Use sendLog - Send debug logs to host from UI: 
    await app.sendLog({ level: "info", data: "Debug message" });
await app.sendLog({ level: "error", data: { error: err.message } });

Add logging to resource handler:

async () => {
  console.error(`[DEBUG] resources/read called for: ${uri}`);
  // ...
}

Common Errors

Error Cause Fix
n.map is not a function Data isn't array Validate with Array.isArray()
UI shows "Loading..." forever connect() not called Add await app.connect()
UI doesn't receive data Handlers set after connect Set handlers BEFORE connect()
TypeScript errors with inputSchema Plain objects used Use Zod schemas
Host doesn't fetch resource Tool missing _meta Use registerAppTool helper
onclick/ondblclick not firing Functions scoped in module Assign to window
MIME type mismatch Hardcoded wrong type Use RESOURCE_MIME_TYPE constant
"UI not built" error Vite didn't run Run npm run build:ui
_meta.ui.resourceUri not in tools/list Using wrong SDK Use @modelcontextprotocol/ext-apps/server
Drag-and-drop not working Event handlers not accessible Use module-internal handlers
Content clipped at edges Missing safe area handling Handle ctx.safeAreaInsets
Theme looks wrong in host Hardcoded colors Use --color-* CSS variables

Summary: The Golden Path

  1. Install: @modelcontextprotocol/ext-apps, @modelcontextprotocol/sdk, zod, vite, vite-plugin-singlefile
  2. Server: Use McpServer + registerAppTool + registerAppResource
  3. Schemas: Use Zod for all tool parameters
  4. UI: Use App from ext-apps, set ALL handlers BEFORE connect()
  5. Streaming: Use ontoolinputpartial for large inputs, ontoolinput for final
  6. Styling: Apply host CSS variables, handle safe area insets
  7. Fullscreen: Check availableDisplayModes, use requestDisplayMode()
  8. Resources: Use IntersectionObserver to pause expensive ops when off-screen
  9. Build: Vite with singlefile plugin, exclude from tsconfig
  10. Test: Verify tools/list shows _meta, resources/read returns HTML, use basic-host

Follow this exactly and MCP Apps will work. Deviate and you'll debug for hours.

This guide merges the official @modelcontextprotocol/ext-apps SDK documentation with battle-tested patterns from real-world debugging. Follow these patterns exactly.