MCP Apps Starter Kit: Interactive UI Views for MCP Servers + Test Host

Build MCP Apps: interactive UIs (charts, forms, tables) that a tool renders inside the chat in hosts implementing the MCP Apps extension (SEP-1865, spec 2026-01-26, io.modelcontextprotocol/ui). It contains a working Python MCP server with 3 views, a dependency-free view bridge, a checker, a headless host for CI and a browser dev host, so you can test without Claude or ChatGPT. Python 3.9+, standard library only. Node 18+ is optional (headless host).

• server/mcp_app_server.py + server/apps.py: an MCP server over stdio (and a minimal Streamable HTTP mode for local testing) with 5 tools and 3 ui:// views. It negotiates the UI extension, falls back to text-only tools for hosts without it, has app-only tools (visibility: ["app"]), and sets _meta.ui csp/permissions/prefersBorder.
• views/bridge.js: under 200 lines and no SDK. It handles the ui/initialize handshake, host theming (CSS variables, light/dark, fonts), auto-resize (size-changed), tool-input/result/cancelled events, tools/call, ui/message, ui/update-model-context, ui/open-link, display modes (checked against host and app capabilities) and teardown. The server inlines it into every view.
• views/, three real examples: - chart.html: an SVG bar chart. Clicking a bar updates the model context, Refresh calls an app-only tool, "Ask" posts a chat message, and it can go fullscreen. - form.html: an approve/reject spend request. It records the decision via an app-only tool, then starts a follow-up turn. - table.html: a sortable issue table with open-in-browser, plus copy-as-Markdown using the clipboardWrite permission.
• tools/mcp_apps_check.py: checks any MCP server (stdio or HTTP): - extension negotiation, _meta.ui.resourceUri (and the deprecated flat key), visibility, ui:// URIs, the exact mimeType and HTML5; - csp origin syntax, and that every external script, style, image, fetch, WebSocket or iframe is declared in csp (or the host's CSP blocks it); - permissions, the text fallback in tool results, and graceful degradation; - --headless also runs every view.
• tools/headless_host.mjs (Node): plays the host. It runs a view's scripts in a sandboxed VM with a minimal DOM, drives initialize -> tool-input -> tool-result -> your --clicks -> teardown, and validates every message. It blocks calls to non-app tools, emulates CSP for fetch, and makes localStorage throw like a sandboxed iframe does. Output is JSON for CI.
• tools/dev_host.py + tools/host.html: a browser preview on 127.0.0.1. The real sandboxed iframe gets a CSP built from your _meta.ui, plus a theme toggle, a chat panel for ui/message, a model context panel, fullscreen, teardown and a full message log.
• tools/new_view.py: scaffolds a new view and prints the code that registers it.
• examples/: broken_server.py (14 checker errors), minimal-view.html, and Claude Desktop / VS Code client configs.
• docs/mcp-apps-cheatsheet.md: every message and rule on one page.

./tools/demo.sh

python3 tools/dev_host.py            # open http://127.0.0.1:8780, pick a tool, Run

python3 tools/mcp_apps_check.py --cmd "node build/index.js"                       # any stdio server, any language
python3 tools/mcp_apps_check.py --url http://127.0.0.1:3000/mcp                   # Streamable HTTP
python3 tools/mcp_apps_check.py --cmd "python3 server.py" --call 'my_tool={"q":"x"}' --headless --json
node tools/headless_host.mjs --server "python3 server.py" --tool my_tool --args '{"q":"x"}' --click submit --json

python3 tools/new_view.py invoice-viewer "Invoice viewer"      # creates views/invoice-viewer.html, prints the apps.py snippet

Paste the snippet into server/apps.py, return your data in structuredContent and a one-line summary in the text content, then run the headless host on it.

Use examples/client-configs/ (Claude Desktop, VS Code) with the absolute path to server/mcp_app_server.py. Hosts that implement MCP Apps render the views. Other hosts get the same tools as plain text. MCP Apps support differs by host, client version and plan, so check your host's docs. Web hosts such as Claude.ai or ChatGPT need a remote HTTPS server with authentication; the bundled --http mode is for local testing.

./run_tests.sh runs 15 Python tests:

• the server: negotiation, UI and text-only tool lists, results, resources, stdio, HTTP;
• the checker on the starter (0 errors, 0 warnings) and on the broken server (every expected finding);
• the headless host on all 3 views with clicks;
• 13 Node unit tests for the bridge;
• the dev host proxy and the scaffolder.

Node-based tests are skipped if Node is missing. The views were also driven in real headless Chromium through the dev host: sorting, model-context updates, tool calls, chat messages, theme switching and iframe auto-resize.

• Written against the MCP Apps spec 2026-01-26 (SEP-1865). Hosts may lag behind or add host-specific rules, for example the domain format.
• The headless host's DOM is minimal: getElementById, createElement, textContent, events and simple selectors. Views built with frameworks (React, Vue) should use the browser dev host. The checker's HTML scan is pattern-based.
• The HTTP mode returns plain JSON (no SSE stream, no auth). It is not a production remote server.
• openLink in the bridge only allows https URLs by design.