Convert Web App
Wrap an existing web UI as a hybrid standalone page and MCP App with server-side tools and resources from one codebase.
Overview
Convert-web-app is an agent skill most often used in Build (also Ship/testing contexts) that adds hybrid MCP App support to an existing web application while preserving standalone use.
Install
npx skills add https://github.com/modelcontextprotocol/ext-apps --skill convert-web-appWhat is this skill?
- Keeps standalone browser behavior while adding MCP App inline rendering in hosts like Claude Desktop
- Thin init layer detects MCP host vs normal page and switches parameter sources
- New MCP server bundles HTML as a resource and registers a display tool
- Shared rendering logic—only the data source changes between modes
- References MCP ext-apps SDK clone for examples and API docs
Adoption & trust: 538 installs on skills.sh; 2.4k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have a web app that works in the browser but cannot render as an MCP App inside Claude Desktop and similar hosts from the same build.
Who is it for?
Indie builders with an existing React/Vue/similar UI who need MCP inline apps without rewriting the frontend.
Skip if: Greenfield MCP-only widgets with no standalone web requirement, or backend-only APIs with no HTML surface.
When should I use this skill?
User asks to add MCP App support, turn a web app into a hybrid MCP App, wrap existing UI, convert iframe embed to MCP App, or add MCP support while keeping standalone web behavior.
What do I get? / Deliverables
You ship one codebase that registers MCP tools and resources so hosts can embed your UI while browsers still load the app normally.
- Hybrid init layer detecting MCP vs browser context
- MCP server registering tool and HTML resource for inline render
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build/integrations is the primary shelf because the work wires an app to MCP hosts via server registration and lifecycle-aware initialization. Integrations captures bridging an existing SPA or web page to external agent hosts without replacing the standalone deployment path.
Where it fits
Register server-side tools and HTML resources so your dashboard appears inside Claude Desktop.
Add MCP lifecycle initialization without forking your SPA’s render tree.
Verify standalone URL params and MCP host parameter fetching both drive the same UI.
How it compares
Skill-guided integration pattern—not a hosted MCP marketplace server and not a raw iframe embed without lifecycle bridging.
Common Questions / FAQ
Who is convert-web-app for?
Developers who already maintain a web application and want MCP App support in agent hosts while keeping normal browser access.
When should I use convert-web-app?
Use in Build when adding MCP App support to a web app; revisit in Ship when validating hybrid behavior in MCP hosts versus standalone deploy.
Is convert-web-app safe to install?
Check this page’s Security Audits panel; implementing the pattern adds an MCP server and may expose bundled HTML—review network and tool permissions you register.
SKILL.md
READMESKILL.md - Convert Web App
# 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: ```bash 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 confir