Add UI to MCP Server Enrich an existing MCP server's tools with interactive UIs using the MCP Apps SDK ( @modelcontextprotocol/ext-apps ). How It Works Existing tools get paired with HTML resources that render inline in the host's conversation. The tool continues to work for text-only clients — UI is an enhancement, not a replacement. Each tool that benefits from UI gets linked to a resource via _meta.ui.resourceUri , and the host renders that resource in a sandboxed iframe when the tool is called. 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 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 , getUiCapability , 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 Key Examples (Mixed Tool Patterns) These examples demonstrate servers with both App-enhanced and plain tools — the exact pattern you're adding: Example Pattern examples/map-server/ show-map (App tool) + geocode (plain tool) examples/pdf-server/ display_pdf (App tool) + list_pdfs (plain tool) + read_pdf_bytes (app-only tool) examples/system-monitor-server/ get-system-info (App tool) + poll-system-stats (app-only polling tool) 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 Step 1: Analyze Existing Tools Before writing any code, analyze the server's existing tools and determine which ones benefit from UI. Read the server source and list all registered tools For each tool, assess whether it would benefit from UI (returns data that could be visualized, involves user interaction, etc.) vs. is fine as text-only (simple lookups, utility functions) Identify tools that could become app-only helpers (data the UI needs to poll/fetch but the model doesn't need to call directly) Present the analysis to the user and confirm which tools to enhance Decision Framework Tool output type UI benefit Example Structured data / lists / tables High — interactive table, search, filtering List of items, search results Metrics / numbers over time High — charts, gauges, dashboards System stats, analytics Media / rich content High — viewer, player, renderer Maps, PDFs, images, video Simple text / confirmations Low — text is fine "File created", "Setting updated" Data for other tools Consider app-only Polling endpoints, chunk loaders Step 2: Add Dependencies npm install @modelcontextprotocol/ext-apps npm install -D vite vite-plugin-singlefile Plus framework-specific dependencies if needed (e.g., react , react-dom , @vitejs/plugin-react for React). 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. Step 3: Set Up the Build Pipeline Vite Configuration Create vite.config.ts with vite-plugin-singlefile to bundle the UI into a single HTML file: import { defineConfig } from "vite" ; import { viteSingleFile } from "vite-plugin-singlefile" ; export default defineConfig ( { plugins : [ viteSingleFile ( ) ] , build : { outDir : "dist" , rollupOptions : { input : "mcp-app.html" , // one per UI, or one shared entry } , } , } ) ; HTML Entry Point Create mcp-app.html (or one per distinct UI if tools need different views): <! doctype html

< html lang = " en "

< head

< meta charset = " UTF-8 " /> < meta name = " viewport " content = " width=device-width, initial-scale=1.0 " /> < title

MCP App </ title

</ head

< body

< div id = " root "

</ div

< script type = " module " src = " ./src/mcp-app.ts "

</ script

</ body

</ html

Build Scripts Add build scripts to package.json . The UI must be built before the server code bundles it: { "scripts" : { "build:ui" : "vite build" , "build:server" : "tsc" , "build" : "npm run build:ui && npm run build:server" , "serve" : "tsx server.ts" } } Step 4: Convert Tools to App Tools Transform plain MCP tools into App tools with UI. Before (plain MCP tool): server . tool ( "my-tool" , { param : z . string ( ) } , async ( args ) => { const data = await fetchData ( args . param ) ; return { content : [ { type : "text" , text : JSON . stringify ( data ) } ] } ; } ) ; After (App tool with UI): import { registerAppTool , registerAppResource , RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server" ; const resourceUri = "ui://my-tool/mcp-app.html" ; registerAppTool ( server , "my-tool" , { description : "Shows data with an interactive UI" , inputSchema : { param : z . string ( ) } , _meta : { ui : { resourceUri } } , } , async ( args ) => { const data = await fetchData ( args . param ) ; return { content : [ { type : "text" , text : JSON . stringify ( data ) } ] , // text fallback for non-UI hosts structuredContent : { data } , // structured data for the UI } ; } ) ; Key guidance: Always keep the content array with a text fallback for text-only clients Add structuredContent for data the UI needs to render Link the tool to its resource via _meta.ui.resourceUri Leave tools that don't benefit from UI unchanged — they stay as plain tools Step 5: Register Resources Register the HTML resource so the host can fetch it: import fs from "node:fs/promises" ; import path from "node:path" ; const resourceUri = "ui://my-tool/mcp-app.html" ; registerAppResource ( server , { uri : resourceUri , name : "My Tool UI" , mimeType : RESOURCE_MIME_TYPE , } , async ( ) => { const html = await fs . readFile ( path . resolve ( import . meta . dirname , "dist" , "mcp-app.html" ) , "utf-8" , ) ; return { contents : [ { uri : resourceUri , mimeType : RESOURCE_MIME_TYPE , text : html } ] } ; } ) ; If multiple tools share the same UI, they can reference the same resourceUri and the same resource registration. Step 6: Build the UI Handler Registration Register ALL handlers BEFORE calling app.connect() : import { App , PostMessageTransport , applyDocumentTheme , applyHostStyleVariables , applyHostFonts } from "@modelcontextprotocol/ext-apps" ; const app = new App ( { name : "My App" , version : "1.0.0" } ) ; app . ontoolinput = ( params ) => { // Render the UI using params.arguments and/or params.structuredContent } ; app . ontoolresult = ( result ) => { // Update UI with final tool result } ; 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 ) ; 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 ( ) => { return { } ; } ; await app . connect ( new PostMessageTransport ( ) ) ; Host Styling Use host CSS variables for theme integration: .container { background : var ( --color-background-secondary ) ; color : var ( --color-text-primary ) ; font-family : var ( --font-sans ) ; border-radius : var ( --border-radius-md ) ; } 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 the full list. For React apps, use the useApp and useHostStyles hooks instead — see basic-server-react/ for the pattern. Optional Enhancements App-Only Helper Tools Tools the UI calls but the model doesn't need to invoke directly (polling, pagination, chunk loading): registerAppTool ( server , "poll-data" , { description : "Polls latest data for the UI" , _meta : { ui : { resourceUri , visibility : [ "app" ] } } , } , async ( ) => { const data = await getLatestData ( ) ; return { content : [ { type : "text" , text : JSON . stringify ( data ) } ] } ; } ) ; The UI calls these via app.callServerTool("poll-data", {}) . CSP Configuration If the UI needs to load external resources (fonts, APIs, CDNs), declare the domains: registerAppResource ( server , { uri : resourceUri , name : "My Tool UI" , mimeType : RESOURCE_MIME_TYPE , _meta : { ui : { connectDomains : [ "api.example.com" ] , // fetch/XHR targets resourceDomains : [ "cdn.example.com" ] , // scripts, styles, images frameDomains : [ "embed.example.com" ] , // nested iframes } , } , } , async ( ) => { / ... / } ) ; Streaming Partial Input For large tool inputs, show progress during LLM generation: app . ontoolinputpartial = ( params ) => { const args = params . arguments ; // Healed partial JSON - always valid // Render preview with partial data } ; app . ontoolinput = ( params ) => { // Final complete input - switch to full render } ; Graceful Degradation with getUiCapability() Conditionally register App tools only when the client supports UI, falling back to text-only tools: import { getUiCapability , registerAppTool , RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server" ; server . server . oninitialized = ( ) => { const clientCapabilities = server . server . getClientCapabilities ( ) ; const uiCap = getUiCapability ( clientCapabilities ) ; if ( uiCap ?. mimeTypes ?. includes ( RESOURCE_MIME_TYPE ) ) { // Client supports UI — register App tool registerAppTool ( server , "my-tool" , { description : "Shows data with interactive UI" , _meta : { ui : { resourceUri } } , } , appToolHandler ) ; } else { // Text-only client — register plain tool server . tool ( "my-tool" , "Shows data" , { param : z . string ( ) } , plainToolHandler ) ; } } ; Fullscreen Mode Allow the UI to expand to fullscreen: app . onhostcontextchanged = ( ctx ) => { if ( ctx . availableDisplayModes ?. includes ( "fullscreen" ) ) { fullscreenBtn . style . display = "block" ; } if ( ctx . displayMode ) { container . classList . toggle ( "fullscreen" , ctx . displayMode === "fullscreen" ) ; } } ; async function toggleFullscreen ( ) { const newMode = currentMode === "fullscreen" ? "inline" : "fullscreen" ; const result = await app . requestDisplayMode ( { mode : newMode } ) ; currentMode = result . mode ; } Common Mistakes to Avoid Forgetting text content fallback — Always include content array with text for non-UI hosts Registering handlers after connect() — Register ALL handlers BEFORE calling app.connect() Missing vite-plugin-singlefile — Without it, assets won't load in the sandboxed iframe Forgetting resource registration — The tool references a resourceUri that must have a matching resource Hardcoding styles — Use host CSS variables ( var(--color-*) ) for theme integration Not handling safe area insets — Always apply ctx.safeAreaInsets in onhostcontextchanged Testing Using basic-host Test the enhanced server 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 ). Verify Plain tools still work and return text output App tools render their UI in the iframe ontoolinput handler fires with tool arguments ontoolresult handler fires with tool result Host styling (theme, fonts, colors) applies correctly