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: Tool - Called by the LLM/host, returns data Resource - Serves the bundled HTML UI that displays the data The tool's _meta.ui.resourceUri references the resource's URI. Host calls tool → Host renders resource UI → Server returns result → 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: server.ts with registerAppTool and registerAppResource main.ts entry point with HTTP and stdio transport setup Client-side app (e.g., src/mcp-app.ts , src/mcp-app.tsx ) with lifecycle handlers src/global.css with global styles and host style variable fallbacks vite.config.ts using vite-plugin-singlefile package.json with npm run scripts and 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 , etc.), lifecycle src/server/index.ts registerAppTool , registerAppResource , helper functions src/spec.types.ts All type definitions: McpUiHostContext , McpUiStyleVariableKey (CSS variable names), McpUiResourceCsp (CSP configuration), etc. src/styles.ts applyDocumentTheme , applyHostStyleVariables , applyHostFonts src/react/useApp.tsx useApp hook for React apps Advanced Patterns See /tmp/mcp-ext-apps/docs/patterns.md for detailed recipes: App-only tools — visibility: ["app"] , hiding tools from model Polling — real-time dashboards, interval management Chunked responses — large files, pagination, base64 encoding Error handling — isError , informing model of failures Binary resources — audio/video/etc via resources/read , blob field Network requests — assets, fetch, CSP, _meta.ui.csp , CORS, _meta.ui.domain Host context — theme, styling, fonts, safe area insets Fullscreen mode — requestDisplayMode , display mode changes Model context — updateModelContext , sendMessage , keeping model informed View state — viewUUID , localStorage, state recovery Visibility-based pause — IntersectionObserver, pausing animations/WebGL Streaming input — ontoolinputpartial , progressive rendering Reference Host Implementation /tmp/mcp-ext-apps/examples/basic-host/ shows one way an MCP Apps-capable host could be implemented. Real-world hosts like Claude Desktop are more sophisticated—use basic-host for local testing and protocol understanding, not as a guarantee of host behavior. Critical Implementation Notes Adding Dependencies Always use npm install to add dependencies rather than manually writing version numbers: npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk zod express cors npm install -D typescript vite vite-plugin-singlefile concurrently cross-env @types/node @types/express @types/cors This lets npm resolve the latest compatible versions. Never specify version numbers from memory. TypeScript Server Execution Unless the user has specified otherwise, use tsx for running TypeScript server files. For example: npm install -D tsx npm pkg set scripts.dev = "cross-env NODE_ENV=development concurrently 'cross-env INPUT=mcp-app.html vite build --watch' 'tsx --watch main.ts'" [!NOTE] The SDK examples use bun but generated projects should default to tsx for broader compatibility. Handler Registration Order Register ALL handlers BEFORE calling app.connect() : const app = new App ( { name : "My App" , version : "1.0.0" } ) ; // Register handlers first app . ontoolinput = ( params ) => { / handle input / } ; app . ontoolresult = ( result ) => { / handle result / } ; app . onhostcontextchanged = ( ctx ) => { / handle context / } ; app . onteardown = async ( ) => { return { } ; } ; // etc. // Then connect await app . connect ( ) ; Common Mistakes to Avoid No text fallback - Always provide content array for non-UI hosts Missing CSP configuration - MCP Apps HTML is served as an MCP resource with no same-origin server; ALL network requests—even to localhost —require a CSP configuration CSP or CORS config in wrong _meta object - _meta.ui.csp and _meta.ui.domain go in the contents[] objects returned by registerAppResource() 's read callback, not in registerAppResource() 's config object Handlers after app.connect() - Register ALL handlers BEFORE calling app.connect() No streaming for large inputs - Use ontoolinputpartial to show progress during input generation Testing Using basic-host Test MCP Apps locally with the basic-host example:

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 ). Debug with sendLog Send debug logs to the host application (rather than just the iframe's dev console): await app . sendLog ( { level : "info" , data : "Debug message" } ) ; await app . sendLog ( { level : "error" , data : { error : err . message } } ) ;