MCP App Template

What it does

MCP App Template is a production-ready starter kit for building MCP Apps — interactive React UI widgets that render directly inside AI hosts like ChatGPT, Claude, VS Code Copilot, and Goose. Instead of your MCP server returning plain text, it returns rich, sandboxed iframes with real interactivity: carousels, dashboards, 3D visualisations, drag-and-drop task managers, QR generators, real-time monitors, and more.

Designed first for coding agents (Claude Code, Codex, Cursor), every piece of infrastructure is optimised so an AI can modify, test, and iterate on widgets without human intervention.

Key features

• 12 production-ready example widgets — carousel, gallery, dashboard, 3D solar system (Three.js), todo (drag-and-drop), shop cart flow, QR generator, system monitor (Chart.js), financial scenario modeller, interactive 3D globe (CesiumJS), and more
• ~450 orthogonal tests auto-discovered per widget — MCP Apps protocol compliance, accessibility, browser rendering in real Chromium via Playwright; tests never break when you change widget content
• Zero-config local app tester powered by Puter.js — no API key required; renders widgets in-chat for instant manual testing
• Automated visual testing for agents — pnpm run ui-test --tool show_carousel renders any widget and writes a screenshot to /tmp/ui-test/screenshot.png so coding agents can verify their changes
• Automated grading reports — MCP best practices, app guidelines, and output quality grades with FIX: hints targeted at coding agents
• One-command scaffold — ./create_new_app.sh strips example widgets, removes unused deps, and leaves a clean slate

Installation

Clone and set up:

git clone https://github.com/sebderhy/mcp-app-template.git my-app
cd my-app
./setup.sh

Start the server:

pnpm run server  # http://localhost:8000

Claude Desktop — expose via tunnel, then add as a custom connector:

npx cloudflared tunnel --url http://localhost:8000

Add the tunnel URL in Claude Settings → Connectors.

ChatGPT — expose via tunnel, enable Developer Mode, then add connector:

Settings → Connectors → <tunnel-url>/mcp

VS Code Copilot — add to settings.json:

"github.copilot.chat.mcp.servers": {
  "mcp-app-template": { "url": "http://localhost:8000/mcp" }
}

Supported hosts

Claude Desktop, Claude.ai, ChatGPT, VS Code Copilot, Goose, Codex, Cursor — any MCP Apps-compatible host.