/convert-web-app

name: convert-web-app
description: This skill should be used when the user asks to "add MCP App support to my web app", "turn my web app into a hybrid MCP App", "make my web page work as an MCP App too", "wrap my existing UI as an MCP App", "convert iframe embed to MCP App", "turn my SPA into an MCP App", or needs to add MCP App support to an existing web application while keeping it working standalone. Provides guidance for analyzing existing web apps and creating a hybrid web + MCP App with server-side tool and resource registration.

Add MCP App Support to a Web App

Add MCP App support to an existing web application so it works both as a standalone web app **and** as an MCP App that renders inline in MCP-enabled hosts like Claude Desktop — from a single codebase.

How It Works

The existing web app stays intact. A thin initialization layer detects whether the app is running inside an MCP host or as a regular web page, and fetches parameters from the appropriate source. A new MCP server wraps the app's bundled HTML as a resource and registers a tool to display it.

Standalone:  Browser loads page → App reads URL params / APIs → renders
MCP App:     Host calls tool → Server returns result → Host renders app in iframe → App reads MCP lifecycle → renders

The app's rendering logic is shared — only the data source changes.

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

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

Reference Examples

| Example | Relevant Pattern | |---------|-----------------| | `examples/map-server/` | External API integration + CSP (`connectDomains`, `resourceDomains`) | | `examples/sheet-music-server/` | Library that loads external assets (soundfonts) | | `examples/pdf-server/` | Binary content handling + app-only helper tools |

Step 1: Analyze the Existing Web App

Before writing any code, examine the existing web app to plan what needs to change.

What to Investigate

1. **Data sources** — How does the app get its data? (URL params, API calls, props, hardcoded, localStorage) 2. **External dependencies** — CDN scripts, fonts, API endpoints, iframe embeds, WebSocket connections 3. **Build system** — Current bundler (Webpack, Vite, Rollup, none), framework (React, Vue, vanilla), entry points 4. **User interactions** — Does the app have inputs/forms that should map to tool parameters? 5. **Runtime detection** — How to tell if the app is running inside an MCP host (e.g., check the current origin, a query param, or whether `window.parent !== window`)

Present findings to the user and confirm the approach.

Data Source Mapping

In hybrid mode, the app keeps its existing data sources for standalone use and adds MCP equivalents:

| Standalone data source | MCP App equivalent | |---|---| | URL query parameters | `ontoolinput` / `ontoolresult` `arguments` or `structuredContent` | | REST API calls | `app.callServerTool()` to server-side tools, or keep direct API calls with CSP `connectDomains` | | Props / component inputs | `ontoolinput` `arguments` | | localStorage / sessionStorage | Not available in sandboxed iframe — pass via `structuredContent` or server-side state | | WebSocket connections | Keep with CSP `connectDomains`, or convert to polling via app-only tools | | Hardcoded data | Move to tool `structuredContent` to make it dynamic |

Step 2: Investigate CSP Requirements

MCP Apps HTML runs in a sandboxed iframe with no same-origin server. **Every** external origin must be declared in CSP — missing origins fail silently.

**Before writing any code**, build the app and investigate all origins it references:

1. Build the app using the existing build command 2. Search the resulting HTML, CSS, and JS for **every** origin (not just "external" origins — every network request will need CSP approval) 3. For each origin found, trace back to source:

• If it comes from a constant → universal (same in dev and prod)
• If it comes from an env var or conditional → note the mechanism and identify both dev and prod values

4. Check for third-party libraries that may make their own requests (analytics, error tracking, etc.)

**Document your findings** as three lists, and note for each origin whether it's universal, dev-only, or prod-only:

• **resourceDomains**: origins serving images, fonts, styles, scripts
• **connectDomains**: origins for API/fetch requests
• **frameDomains**: origins for nested iframes

If no origins are found, the app may not need custom CSP domains.

Step 3: Set Up the MCP Server

Create a new MCP server with tool and resource r