MCP Apps Builder (ext-apps Agent Skills bridge)

The Model Context Protocol ext-apps repo ships four official Agent Skills that teach an AI coding agent how to build MCP Apps (SEP-1865 — interactive ui:// UIs that render inside a chat host). This skill tells you when to reach for them and how to install them, so MCP App work is done with the canonical, up-to-date guidance instead of guesswork.

The four builder skills

Skill	Use it when…
create-mcp-app	Scaffolding a new MCP App (server + interactive UI) from scratch.
add-app-to-server	Adding an interactive ui:// view to an existing MCP server's tools.
migrate-oai-app	Converting an existing OpenAI Apps SDK app to MCP Apps.
convert-web-app	Turning an existing web app into a hybrid web + MCP App.

Install / load them

Pick whichever matches the agent you're driving (skills live in the agent's skills directory — install once, then ask the agent to build):

• Claude Code (plugin marketplace):

  /plugin marketplace add modelcontextprotocol/ext-apps
  /plugin install mcp-apps@modelcontextprotocol-ext-apps
  

• Any agent (Vercel Skills CLI):

  npx skills add modelcontextprotocol/ext-apps
  

• Manual (clone + copy into the agent's skills dir):

  git clone https://github.com/modelcontextprotocol/ext-apps.git
  cp -r ext-apps/plugins/mcp-apps/skills/create-mcp-app ~/.kiro/skills/create-mcp-app
  # …repeat for add-app-to-server / migrate-oai-app / convert-web-app
  

  Skills dirs by agent: Kiro CLI ~/.kiro/skills/, Claude Code ~/.claude/skills/, VS Code/Copilot ~/.copilot/skills/, Gemini CLI ~/.gemini/skills/, Codex ~/.codex/skills/, Cursor ~/.cursor/skills/, Goose ~/.config/goose/skills/. Verify with: ask the agent "what skills do you have?"

For complete per-agent installation instructions and troubleshooting, see references/installation-per-agent.md.

Building inside CAO (read this for ui://cao/* work)

CAO's own views (ui://cao/dashboard / agent / event-stream) are hand-rolled single-file React bundles — not generated by create-mcp-app — because CAO enforces stricter invariants than the starter templates. When you add a new CAO view, use add-app-to-server's checklist for the spec-correct shape, but keep CAO's guardrails:

• Default-off behind CAO_MCP_APPS_ENABLED (end to end).
• JIT-free bundles (no eval / new Function; the host CSP forbids it; the scan:jit gate fails otherwise).
• HTTP-only boundary: mcp_server/* reaches state only over HTTP (AST guard test/test_http_only_boundary.py).
• Stay within the bundle-size budget (check:size) and the coverage ratchet (coverage:ratchet).
• Tag tools with ui_meta(...) (resource _meta.ui: csp / permissions / domain / prefersBorder; tool _meta.ui: resourceUri / visibility).

For the full guardrail checklist and how to run each CI gate locally, see references/cao-view-guardrails.md.

For the operator/extend playbook (turn it on, troubleshoot, the submit_command choke point, host-delegated actions), load the cao-mcp-apps skill.

Sources of truth

• MCP Apps Overview · Build an MCP App
• Stable spec 2026-01-26/apps.mdx · SDK @modelcontextprotocol/ext-apps (v1.7.4) · API reference
• ext-apps repo · client matrix

Gotchas

• CAO views are NOT generated by create-mcp-app: CAO's own ui://cao/* views are hand-rolled single-file React bundles with stricter invariants than the starter templates. Use add-app-to-server for the spec-correct shape, but enforce CAO's guardrails (JIT-free, bundle-size budget, HTTP-only boundary).
• JIT-free is non-negotiable for CAO: Host CSP forbids eval / new Function. The CI scan:jit gate will fail the build if any JIT constructs are present.
• HTTP-only boundary: mcp_server/* must reach state only over HTTP to the Backplane. The AST guard test (test/test_http_only_boundary.py) enforces this — direct state access bypasses governance.

Build → Test → Record Workflow

When building or extending CAO MCP Apps views, always follow this complete cycle:

cd cao_mcp_apps
npm run build:all         # Build all view bundles (single-file HTML)
npm test                  # Unit tests (vitest)
npm run test:e2e          # Playwright E2E against built bundles
npm run demo              # Record demo video + screenshots + GIF

The npm run demo step captures the current state of all views (including the unified fleet command center) into docs/media/ — this is what README.md and docs/mcp-apps.md display. Always regenerate after modifying views so documentation stays current.

For CAO-specific views (ui://cao/*), also verify:

• Bundle size within budget: npm run check:size
• No JIT constructs: npm run scan:jit
• TypeScript strict: npx tsc --noEmit

For installation details per agent host, see references/installation-per-agent.md. For CAO view guardrails, see references/cao-view-guardrails.md.