mcp-apps-builder

# MCP Apps Builder (ext-apps Agent Skills bridge)

The Model Context Protocol [ext-apps](https://github.com/modelcontextprotocol/ext-apps)
repo ships **four official Agent Skills** that teach an AI coding agent how to
build [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview)
(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`](https://github.com/modelcontextprotocol/ext-apps) | Scaffolding a **new** MCP App (server + interactive UI) from scratch. |
| [`add-app-to-server`](https://github.com/modelcontextprotocol/ext-apps) | Adding an interactive `ui://` view to an **existing** MCP server's tools. |
| [`migrate-oai-app`](https://github.com/modelcontextprotocol/ext-apps) | Converting an existing **OpenAI Apps SDK** app to MCP Apps. |
| [`convert-web-app`](https://github.com/modelcontextprotocol/ext-apps) | 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](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](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](https://modelcontextprotocol.io/extensions/apps/overview) ·
  [Build an MCP App](https://modelcontextprotocol.io/extensions/apps/build)
- Stable spec [`2026-01-26/apps.mdx`](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx) ·
  SDK [`@modelcontextprotocol/ext-apps`](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) (v1.7.4) ·
  [API reference](https://apps.extensions.modelcontextprotocol.io/api/index.html)
- [ext-apps repo](https://github.com/modelcontextprotocol/ext-apps) ·
  [client matrix](https://modelcontextprotocol.io/extensions/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:

```bash
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](references/installation-per-agent.md).
For CAO view guardrails, see [references/cao-view-guardrails.md](references/cao-view-guardrails.md).