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:

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/:

Framework Templates

Learn and adapt from /tmp/mcp-ext-apps/examples/basic-server-{framework}/:

Reference Examples

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:

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

1. 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 registration. This wraps the existing web app for MCP hosts.

Dependencies

npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@^2.0.0 @modelcontextprotocol/server@^2.0.0 zod@^4.2.0
npm install -D tsx vite vite-plugin-singlefile

Use npm install so the package manager resolves versions; ext-apps 2.x needs the split base MCP SDK packages at ^2.0.0 (@modelcontextprotocol/core comes in transitively). Do not add the legacy @modelcontextprotocol/sdk v1 package or substitute unpublished local packages.

Server Code

Create server.ts:

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
import fs from "node:fs/promises";
import path from "node:path";
import { z } from "zod";

const server = new McpServer({ name: "my-app", version: "1.0.0" });

const resourceUri = "ui://my-app/mcp-app.html";

// Register the tool — inputSchema maps to the app's data sources
registerAppTool(server, "show-app", {
  description: "Displays the app with the given parameters",
  inputSchema: z.object({
    query: z.string().describe("The search query"),
  }),
  _meta: { ui: { resourceUri } },
}, async (args) => {
  // Process args server-side if needed
  return {
    content: [{ type: "text", text: `Showing app for: ${args.query}` }],
    structuredContent: { query: args.query },
  };
});

// Register the HTML resource
registerAppResource(
  server,
  "My App UI",
  resourceUri,
  {},
  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,
          // Add CSP domains from Step 2 if needed:
          // _meta: { ui: { csp: { connectDomains: ["https://api.example.com"], resourceDomains: ["https://cdn.example.com"] } } },
        },
      ],
    };
  },
);

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

Package Scripts

Add to package.json:

{
  "scripts": {
    "build:ui": "vite build",
    "build:server": "tsc",
    "build": "npm run build:ui && npm run build:server",
    "serve": "tsx server.ts"
  }
}

Step 4: Adapt the Build Pipeline