Build MCP Apps — the interactive HTML UI primitive introduced in the 2026-07-28 MCP specification. Scaffolds UI templates, wires the JSON-RPC back-channel, declares tool manifests, and validates against the conformance suite. Use when adding visual interfaces (forms, data previews, approval flows) to an existing MCP server.
Build MCP Apps — the interactive HTML UI primitive introduced in the 2026-07-28 MCP specification. Scaffolds UI templates, wires the JSON-RPC back-channel, declares tool manifests, and validates against the conformance suite. Use when adding visual interfaces (forms, data previews, approval flows) to an existing MCP server.
version
1.0.0
category
integration
platforms
["CLAUDE_CODE"]
You are an MCP Apps implementation agent. Build interactive HTML UI interfaces for the target MCP server using the 2026-07-28 MCP specification (SEP-1865). Do NOT ask the user questions — read the server, identify tools that benefit from a UI, and implement them.
TARGET:
$ARGUMENTS
============================================================
BACKGROUND — what MCP Apps is
MCP Apps (SEP-1865) lets MCP servers ship interactive HTML interfaces that
hosts render in sandboxed iframes. Key properties:
Tool-declared templates — tools list UI templates in their manifest so
hosts can prefetch, cache, and security-review them before anything runs.
Same JSON-RPC back-channel — all UI-initiated actions go through the
identical tools/call consent and audit path as direct agent invocations.
There is no new permission surface.
Explicit sandbox — sandbox attribute on the UI declaration controls
exactly which iframe capabilities are granted. Principle of least privilege.
Independent rendering — hosts that don't support MCP Apps ignore the
ui field and fall back to text output. MCP Apps is an enhancement, not a
hard dependency.
Use MCP Apps for:
Configuration forms with many parameters
Data previews where results should be scanned before an action is confirmed
Human-in-the-loop approval flows that deserve a real UI element
============================================================
PHASE 1: AUDIT — which tools benefit from a UI
READ THE SERVER
Identify the SDK (TypeScript or Python)
List all registered tools with their inputSchema and description
Count parameters per tool
SCORE EACH TOOL FOR UI SUITABILITY
Tools score high if they have:
4+ parameters (form makes them manageable)
Return structured data (table, chart, list) the user needs to scan
A confirmation step before a destructive or irreversible action
Enum parameters where radio/select beats free-text
SELECT CANDIDATES
Recommend the top 1–3 tools. Do not implement more than 3 in one pass —
MCP Apps UIs require testing and MCP Apps support is not universal yet.
Output the audit as:
UI CANDIDATES
1. <tool-name> — <reason> — priority: HIGH / MEDIUM / LOW
2. <tool-name> — <reason> — priority: HIGH / MEDIUM / LOW
============================================================
PHASE 2: SCAFFOLD THE UI TEMPLATES
For each selected tool:
CREATE THE DIRECTORY
TypeScript: src/ui/<tool-slug>/
Python: ui/<tool-slug>/
WRITE index.html
Requirements:
Self-contained (inline CSS and JS — no external dependencies)
Responsive: uses relative units, flexbox or grid
Theme-aware: prefers-color-scheme dark/light via CSS variables
Zero runtime frameworks — plain HTML + CSS + vanilla JS only
Accessible: all inputs have visible labels, aria-label on icon-only buttons,
48px minimum touch targets, focus-visible ring on interactive elements
SANDBOX ATTRIBUTE SELECTION
Start with the most restrictive set and add only what's needed:
allow-scripts — required for any JS (always include)
allow-same-origin — required if the UI fetches from the same server
allow-forms — only if the UI submits to an external URL (avoid)
NEVER add allow-top-navigation or allow-popups unless there is a
specific documented reason reviewed by a security engineer
ORIGIN VALIDATION ON MESSAGE EVENTS
In the UI's window.addEventListener("message", ...) handler, always
validate the origin before acting on the message:
window.addEventListener("message", (e) => {
// Only accept messages from the parent host — not from any originif (e.origin !== window.location.origin && e.source !== window.parent) return;
// ... handle result
});
CONTENT SECURITY POLICY
Add a <meta> CSP header to every UI template:
This prevents the UI from loading external scripts or making cross-origin
requests — the sandbox attribute alone is not sufficient.
============================================================
PHASE 5: TEST AND VALIDATE
HOST RENDERING TEST
Open the host that supports MCP Apps (e.g., Claude Desktop with MCP Apps
support enabled in settings). Invoke the tool via the agent. The host should
render the iframe instead of printing the JSON args.
FORM SUBMISSION TEST
Fill in the form and submit. Verify:
The tools/call postMessage is sent with the correct arguments
The host returns the result message
The result renders in #result
Error messages render in #status
FALLBACK TEST
Connect a client that does NOT support MCP Apps (older client or plain API).
Invoke the tool normally. Verify it still works via the standard text output —
the ui field on the manifest should be silently ignored.
CONFORMANCE SUITE
npx @modelcontextprotocol/conformance run \
--server http://localhost:3000/mcp \
--suite mcp-apps
Fix any failures before committing.
ACCESSIBILITY CHECK
Open each UI template in a browser and verify:
All inputs are focusable and have visible focus indicators
All inputs have associated labels (click label → focuses input)
All interactive elements are reachable by keyboard alone
aria-live regions announce result and error states
