/create-mcp-app

name: create-mcp-app
description: 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, or host integration. Provides comprehensive guidance for building MCP Apps with interactive UIs.

Create MCP App

Build interactive UIs that run inside MCP-enabled hosts like Claude Desktop. An MCP App combines an MCP tool with an HTML resource to display rich, interactive content.

Core Concept: Tool + Resource

Every MCP App requires two parts linked together:

1. **Tool** - Called by the LLM/host, returns data 2. **Resource** - Serves the bundled HTML UI that displays the data 3. **Link** - The tool's `_meta.ui.resourceUri` references the resource

Host calls tool → Server returns result → Host renders resource UI → UI receives result

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/Svelte/Preact/Solid | Manual lifecycle | Framework preference |

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`

Getting 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` |

Critical Implementation Notes

Adding Dependencies

Use `npm install` to add dependencies rather than manually writing version numbers:

npm install