| name | Generate Interactive MCP App |
| description | A comprehensive framework for building interactive, UI-based Model Context Protocol (MCP) apps for Claude. |
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:
- Define the backend dependencies and initialize the
package.json with correct build scripts (e.g., tsc && vite build).
- Write the backend logic (
server.ts and main.ts) defining the necessary tools and McpServer setup.
- Write the frontend React logic (
mcp-app.tsx), tightly binding the useApp hook with UI state.
- Implement standard CSS and safe area padding calculations.
- Provide the user with a setup guide on how to register the app in their
claude_desktop_config.json.
