← Async Tasks (SEP-1686) — Call-Now, Fetch-Later for Long-Running Work MCP Security I — Tool Poisoning, Rug Pulls, Cross-Server Shadowing →

MCP Apps — Interactive UI Resources via `ui://`

> Text-only tool output caps what agents can show. MCP Apps (SEP-1724, official January 26, 2026) let a tool return sandboxed interactive HTML rendered inline in Claude Desktop, ChatGPT, Cursor, Goose, and VS Code. Dashboards, forms, maps, 3D scenes, all through one extension. This lesson walks the ui:// resource scheme, the text/html;profile=mcp-app MIME, the iframe-sandbox postMessage protocol, and the security surface that comes with letting a server render HTML.

Type: Build

Languages: Python (stdlib, UI resource emitter), HTML (sample app)

Prerequisites: Phase 13 · 07 (MCP server), Phase 13 · 10 (resources)

Time: ~75 minutes

Learning Objectives

Return a ui:// resource from a tool call and set the correct MIME and metadata.
Declare a tool's associated UI with _meta.ui.resourceUri, _meta.ui.csp, and _meta.ui.permissions.
Implement the iframe sandbox postMessage JSON-RPC for UI-to-host communication.
Apply CSP and permissions-policy defaults that defend against UI-originated attacks.

The Problem

A 2025-era visualize_timeline tool can return "Here are 14 notes organized chronologically: ...". That is a paragraph. Users actually want the interactive timeline. Before MCP Apps, the options were: client-specific widget APIs (Claude artifacts, OpenAI Custom GPT HTML), or no UI at all.

MCP Apps (SEP-1724, shipped January 26, 2026) standardize the contract. A tool result contains a resource whose URI is ui://... and whose MIME is text/html;profile=mcp-app. The host renders it in a sandboxed iframe with a limited CSP and no network access unless explicitly granted. The UI inside the iframe posts messages to the host via a tiny postMessage JSON-RPC dialect.

Every compatible client (Claude Desktop, ChatGPT, Goose, VS Code) renders the same ui:// resource the same way. One server, one HTML bundle, universal UI.

The Concept

The `ui://` resource scheme

A tool returns:

{
  "content": [
    {"type": "text", "text": "Here is your notes timeline:"},
    {"type": "ui_resource", "uri": "ui://notes/timeline"}
  ],
  "_meta": {
    "ui": {
      "resourceUri": "ui://notes/timeline",
      "csp": {
        "defaultSrc": "'self'",
        "scriptSrc": "'self' 'unsafe-inline'",
        "connectSrc": "'self'"
      },
      "permissions": []
    }
  }
}

The host then calls resources/read on the ui://notes/timeline URI and gets back:

{
  "contents": [{
    "uri": "ui://notes/timeline",
    "mimeType": "text/html;profile=mcp-app",
    "text": "<!doctype html>..."
  }]
}

Iframe sandbox

The host renders the HTML inside a sandboxed </code> with:</p> <ul> <li><code>sandbox="allow-scripts allow-same-origin"</code> (or stricter per server declaration)</li> <li>Server-declared CSP applied via response headers.</li> <li>No cookies, no localStorage from the host's origin.</li> <li>Network access limited to <code>connectSrc</code> in CSP.</li> </ul> <h3 id="postmessage-protocol">postMessage protocol</h3> <p>The iframe communicates with the host via <code>window.postMessage</code>. A tiny JSON-RPC 2.0 dialect:</p> <p>Always pin <code>targetOrigin</code> to the peer's exact origin, and on the receiving side validate <code>event.origin</code> against an allowlist before processing any payload. Never use <code>"*"</code> for either side of this channel — the body carries tool calls and resource reads.</p> <pre><code>// iframe to host (pin to host origin) window.parent.postMessage({ jsonrpc: "2.0", id: 1, method: "host.callTool", params: { name: "notes_update", arguments: { id: "note-14", title: "..." } } }, "https://host.example.com"); // host to iframe (pin to iframe origin) iframe.contentWindow.postMessage({ jsonrpc: "2.0", id: 1, result: { content: [...] } }, "https://iframe.example.com"); // receiver on both sides window.addEventListener("message", (event) => { if (event.origin !== "https://expected-peer.example.com") return; // safe to process event.data });</code></pre> <p>Available host-side methods the UI can call:</p> <ul> <li><code>host.callTool(name, arguments)</code> — invokes a server tool.</li> <li><code>host.readResource(uri)</code> — reads an MCP resource.</li> <li><code>host.getPrompt(name, arguments)</code> — fetches a prompt template.</li> <li><code>host.close()</code> — dismisses the UI.</li> </ul> <p>Every call still goes through the MCP protocol and inherits the server's permissions.</p> <h3 id="permissions">Permissions</h3> <p>The <code>_meta.ui.permissions</code> list requests extra capabilities:</p> <ul> <li><code>camera</code> — access the user's camera (used for scan-a-document UIs).</li> <li><code>microphone</code> — voice input.</li> <li><code>geolocation</code> — location.</li> <li><code>network:*</code> — wider network access than <code>connectSrc</code> alone allows.</li> </ul> <p>Each permission is a prompt the user sees before the UI renders.</p> <h3 id="security-risks">Security risks</h3> <p>HTML in an iframe is still HTML. New attack surface:</p> <ul> <li><strong>Prompt-injection via UI.</strong> A malicious server UI can show text that looks like a system message and tricks the user. Host rendering should visibly distinguish server UI from host UI.</li> <li><strong>Exfiltration via <code>connectSrc</code>.</strong> If CSP permits <code>connect-src: *</code>, the UI can send data anywhere. Default should be strict.</li> <li><strong>Clickjacking.</strong> The UI overlays host chrome. Hosts must prevent z-index manipulation and enforce opacity rules.</li> <li><strong>Steal focus.</strong> UI takes keyboard focus and captures the next message. Hosts must intercept.</li> </ul> <p>Phase 13 · 15 covers these in depth as part of MCP security; this lesson introduces them.</p> <h3 id="uiinitialize-handshake"><code>ui/initialize</code> handshake</h3> <p>After the iframe loads, it sends <code>ui/initialize</code> over postMessage:</p> <pre><code>{"jsonrpc": "2.0", "id": 0, "method": "ui/initialize", "params": {"theme": "dark", "locale": "en-US", "sessionId": "..."}}</code></pre> <p>Host responds with capabilities and a session token. The UI uses the session token on every subsequent host call.</p> <h3 id="apprenderer-appframe-sdk-primitives">AppRenderer / AppFrame SDK primitives</h3> <p>The ext-apps SDK exposes two convenience primitives:</p> <ul> <li><code>AppRenderer</code> (server side) — wraps a React / Vue / Solid component and emits a <code>ui://</code> resource with the right MIME and metadata.</li> <li><code>AppFrame</code> (client side) — receives the resource, mounts the iframe, and mediates postMessage.</li> </ul> <p>You can use these or hand-roll the HTML and JSON-RPC.</p> <h3 id="ecosystem-status">Ecosystem status</h3> <p>MCP Apps shipped January 26, 2026. Client support as of April 2026:</p> <ul> <li><strong>Claude Desktop.</strong> Full support since January 2026.</li> <li><strong>ChatGPT.</strong> Full support via the Apps SDK (same underlying MCP Apps protocol).</li> <li><strong>Cursor.</strong> Beta; enable via settings.</li> <li><strong>VS Code.</strong> Insider builds only.</li> <li><strong>Goose.</strong> Full support.</li> <li><strong>Zed, Windsurf.</strong> Roadmapped.</li> </ul> <p>Servers in production: dashboards, map visualizations, data tables, chart builders, sandbox IDE previews.</p> <h2 id="use-it">Use It</h2> <p><code>code/main.py</code> extends the notes server with a <code>visualize_timeline</code> tool that returns a <code>ui://notes/timeline</code> resource, plus a handler for <code>resources/read</code> on that URI which returns a small but complete HTML bundle with an SVG timeline. The HTML is stdlib-templated — no build system. postMessage is sketched in JS comments since stdlib cannot drive a browser.</p> <p>What to look at:</p> <ul> <li><code>_meta.ui</code> on the tool response carries resourceUri, CSP, permissions.</li> <li>The HTML renders without network access; all data is inlined.</li> <li>JS calls <code>host.callTool</code> via <code>window.parent.postMessage</code> (documented but inert in this stdlib demo).</li> </ul> <h2 id="ship-it">Ship It</h2> <p>This lesson produces <code>outputs/skill-mcp-apps-spec.md</code>. Given a tool that would benefit from an interactive UI, the skill produces the full MCP Apps contract: <code>ui://</code> URI, CSP, permissions, postMessage entrypoints, and a security checklist.</p> <h2 id="exercises">Exercises</h2> <ol> <li>Run <code>code/main.py</code> and inspect the HTML emitted. Open the HTML directly in a browser; verify the SVG renders. Then sketch the postMessage contract the UI would use to call <code>host.callTool("notes_update", ...)</code>.</li> </ol> <ol> <li>Tighten the CSP: remove <code>'unsafe-inline'</code> and use a nonce-based script policy. What changes in the HTML generation code?</li> </ol> <ol> <li>Add a second UI resource <code>ui://notes/editor</code> with a form for editing a note in place. When the user submits, the iframe calls <code>host.callTool("notes_update", ...)</code>.</li> </ol> <ol> <li>Audit the UI's attack surface. Where could a malicious server inject content? What does the iframe sandbox defend against and what does it not?</li> </ol> <ol> <li>Read the SEP-1724 spec and identify one capability in the MCP Apps SDK that this toy implementation does not use. (Hint: component-level state sync.)</li> </ol> <h2 id="key-terms">Key Terms</h2> <table class="tbl"> <tr> <th>Term</th> <th>What people say</th> <th>What it actually means</th> </tr> <tr> <td>MCP Apps</td> <td>"Interactive UI resources"</td> <td>SEP-1724 extension shipped 2026-01-26</td> </tr> <tr> <td><code>ui://</code></td> <td>"App URI scheme"</td> <td>Resource scheme for UI bundles</td> </tr> <tr> <td><code>text/html;profile=mcp-app</code></td> <td>"The MIME"</td> <td>Content-type for MCP App HTML</td> </tr> <tr> <td>Iframe sandbox</td> <td>"Render container"</td> <td>Browser sandboxing of the UI with CSP and permissions</td> </tr> <tr> <td>postMessage JSON-RPC</td> <td>"UI-to-host wire"</td> <td>Tiny JSON-RPC-over-postMessage dialect for host calls</td> </tr> <tr> <td><code>_meta.ui</code></td> <td>"Tool-UI binding"</td> <td>Metadata linking a tool result to a UI resource</td> </tr> <tr> <td>CSP</td> <td>"Content-Security-Policy"</td> <td>Declares allowed sources for scripts, network, styles</td> </tr> <tr> <td>AppRenderer</td> <td>"Server SDK primitive"</td> <td>Converts a framework component into a <code>ui://</code> resource</td> </tr> <tr> <td>AppFrame</td> <td>"Client SDK primitive"</td> <td>Iframe mount helper that mediates postMessage</td> </tr> <tr> <td><code>ui/initialize</code></td> <td>"Handshake"</td> <td>First postMessage from UI to host</td> </tr> </table> <h2 id="further-reading">Further Reading</h2> <ul> <li><a href="https://github.com/modelcontextprotocol/ext-apps">MCP ext-apps — GitHub</a> — reference implementation and SDK</li> <li><a href="https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx">MCP Apps specification 2026-01-26</a> — formal spec document</li> <li><a href="https://modelcontextprotocol.io/extensions/apps/overview">MCP — Apps extension overview</a> — high-level documentation</li> <li><a href="https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/">MCP blog — MCP Apps launch</a> — January 2026 launch post</li> <li><a href="https://apps.extensions.modelcontextprotocol.io/api/">MCP Apps API reference</a> — JSDoc-style SDK reference</li> </ul> <div class="nav-links"><a href="/phases/13-tools-and-protocols/13-mcp-async-tasks/">← Async Tasks (SEP-1686) — Call-Now, Fetch-Later for Long-Running Work</a><a href="/phases/13-tools-and-protocols/15-mcp-security-tool-poisoning/">MCP Security I — Tool Poisoning, Rug Pulls, Cross-Server Shadowing →</a></div></main> <aside class="toc"><h3>On this page</h3><a href="#learning-objectives">Learning Objectives</a> <a href="#the-problem">The Problem</a> <a href="#the-concept">The Concept</a> <a href="#the-ui-resource-scheme" class="h3">The <code>ui://</code> resource scheme</a> <a href="#iframe-sandbox" class="h3">Iframe sandbox</a> <a href="#postmessage-protocol" class="h3">postMessage protocol</a> <a href="#permissions" class="h3">Permissions</a> <a href="#security-risks" class="h3">Security risks</a> <a href="#uiinitialize-handshake" class="h3"><code>ui/initialize</code> handshake</a> <a href="#apprenderer-appframe-sdk-primitives" class="h3">AppRenderer / AppFrame SDK primitives</a> <a href="#ecosystem-status" class="h3">Ecosystem status</a> <a href="#use-it">Use It</a> <a href="#ship-it">Ship It</a> <a href="#exercises">Exercises</a> <a href="#key-terms">Key Terms</a> <a href="#further-reading">Further Reading</a></aside> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16/dist/katex.min.css"> <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/katex@0.16/dist/katex.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/katex@0.16/dist/contrib/auto-render.min.js"></script> <script> mermaid.initialize({startOnLoad:false,theme:'default'}) document.addEventListener('DOMContentLoaded',function(){ mermaid.run({querySelector:'.mermaid'}) renderMathInElement(document.body,{ delimiters:[ {left:'$$',right:'$$',display:true}, {left:'$',right:'$',display:false}, {left:'\$',right:'\$',display:false}, {left:'\\[',right:'\\]',display:true}, ], throwOnError:false }) }) // Phase accordion document.querySelectorAll('.phase-title').forEach(el=>{ el.style.cursor='pointer' el.onclick=function(e){ e.preventDefault();e.stopPropagation() this.parentElement.classList.toggle('open') } }) // Close nav on link click (mobile) document.querySelectorAll('nav a').forEach(a=>{ a.addEventListener('click',function(){ document.querySelector('nav').classList.remove('open') document.querySelector('.overlay').classList.remove('active') }) }) // Highlight current lesson + auto-open phase var active=document.querySelector('nav a.active') if(active){ var p=active.closest('.phase') if(p) p.classList.add('open') } // Copy buttons document.querySelectorAll('main pre').forEach(pre=>{ var btn=document.createElement('button') btn.className='copy-btn';btn.textContent='Copy' btn.onclick=function(){ var code=pre.querySelector('code') var text=code?code.textContent:pre.textContent.replace(/^Copy/,'') navigator.clipboard.writeText(text).then(()=>{ btn.textContent='Copied!';btn.classList.add('copied') setTimeout(()=>{btn.textContent='Copy';btn.classList.remove('copied')},2000) }) } pre.appendChild(btn) }) // Scroll-spy for ToC var tocLinks=document.querySelectorAll('aside.toc a') if(tocLinks.length){ var headings=[] tocLinks.forEach(a=>{ var id=a.getAttribute('href').slice(1) var el=document.getElementById(id) if(el) headings.push({el:el,link:a}) }) var observer=new IntersectionObserver(entries=>{ entries.forEach(e=>{ var link=document.querySelector('aside.toc a[href="#'+e.target.id+'"]') if(link) link.classList.toggle('active-toc',e.isIntersecting) }) },{rootMargin:'-10% 0px -70% 0px'}) headings.forEach(h=>observer.observe(h.el)) } </script> </body> </html>