Generate Interactive MCP App

Generate Interactive MCP App

This skill provides the structure and instructions required to build an interactive, frontend-enabled MCP application using React, Vite, and the Model Context Protocol ext-apps SDK.

Requirements

When building an interactive MCP app, you must abide by the following architectural constraints:

1. Build System & Bundling

• Utilize Vite along with vite-plugin-singlefile. Interactive MCP apps serve their frontend via custom URI protocols (ui://...), making it highly advantageous to bundle the entire React application (HTML, CSS, JS) into a single file to simplify resource serving.
• The mcp-app.html file must act as the Vite input.

2. Required File Structure

Your generated workspace should include at least the following:

• package.json: Include @modelcontextprotocol/sdk, @modelcontextprotocol/ext-apps, react, and vite.
• main.ts: The entry point that opens the transport (e.g., StdioServerTransport for Claude Desktop).
• server.ts: Initializes McpServer, sets up tools, and exposes the UI resource.
• vite.config.ts: Configures the single-file plugin.
• mcp-app.html: Boilerplate HTML container.
• src/mcp-app.tsx: The React entrypoint demonstrating the useApp hook.
• src/global.css & src/mcp-app.module.css: Global baseline and scoped CSS Modules.

3. Connection and Logic (src/mcp-app.tsx)

• Use the useApp hook from @modelcontextprotocol/ext-apps/react to wire the UI to the MCP host.
• Handle app.onhostcontextchanged to calculate safeAreaInsets and prevent the UI from being clipped by the Claude Desktop interface.
• Handle app.ontoolresult to parse incoming data generated by standard MCP tool calls.
• Use app.callServerTool({ name, arguments }) to execute logic directly from user interactions in the UI.

4. Styling and Theming Rules

• Color Scheme: Include <meta name="color-scheme" content="light dark"> in the HTML head.
• CSS Modules: Prefer CSS Modules (*.module.css) to prevent style collisions between different parts of the interactive card.
• Safe Area Insets: Always apply padding to the main container mapping to the host's safe area (hostContext.safeAreaInsets.top|bottom|left|right).

AI Implementation Steps

When asked to create an MCP UI application, follow these sequential steps:

1. Define the backend dependencies and initialize the package.json with correct build scripts (e.g., tsc && vite build).
2. Write the backend logic (server.ts and main.ts) defining the necessary tools and McpServer setup.
3. Write the frontend React logic (mcp-app.tsx), tightly binding the useApp hook with UI state.
4. Implement standard CSS and safe area padding calculations.
5. Provide the user with a setup guide on how to register the app in their claude_desktop_config.json.