From 75f02ab4e3d03617dd572f78994df37a775be682 Mon Sep 17 00:00:00 2001 From: thein Date: Sat, 14 Nov 2026 22:10:16 -0500 Subject: [PATCH] docs: add add-apps-to-host skill and host explainer Adds a fifth agent skill, add-apps-to-host, for building the host side of MCP Apps in TypeScript: the sandbox proxy page on a separate origin, the AppFrame component that owns the iframe and AppBridge, and the backend endpoints they rely on. The skill walks through the required startup order, the four UI-to-model routes, persistence and re-drawing, the spec's security rules (origin split, CSP as an HTTP header, visibility checks), common mistakes, and a test plan using the repo's example servers. Also adds docs/building-a-host.html, a standalone visual walkthrough of the same material, and lists the new skill in docs/agent-skills.md, the plugin README and AGENTS.md. --- AGENTS.md | 3 + docs/agent-skills.md | 6 +- docs/building-a-host.html | 2008 +++++++++++++++++ plugins/mcp-apps/README.md | 7 + .../mcp-apps/skills/add-apps-to-host/SKILL.md | 214 ++ .../add-apps-to-host/references/app-frame.md | 517 +++++ .../references/backend-contract.md | 214 ++ .../references/sandbox-proxy.md | 295 +++ 8 files changed, 3262 insertions(+), 2 deletions(-) create mode 100644 docs/building-a-host.html create mode 100644 plugins/mcp-apps/skills/add-apps-to-host/SKILL.md create mode 100644 plugins/mcp-apps/skills/add-apps-to-host/references/app-frame.md create mode 100644 plugins/mcp-apps/skills/add-apps-to-host/references/backend-contract.md create mode 100644 plugins/mcp-apps/skills/add-apps-to-host/references/sandbox-proxy.md diff --git a/AGENTS.md b/AGENTS.md index 219b94718..c28a403ef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -101,3 +101,6 @@ The `plugins/mcp-apps/` directory contains a Claude Code plugin distributed via - `plugins/mcp-apps/skills/create-mcp-app/SKILL.md` — for creating an MCP App - `plugins/mcp-apps/skills/migrate-oai-app/SKILL.md` — for migrating an app from the OpenAI Apps SDK to the MCP Apps SDK +- `plugins/mcp-apps/skills/add-app-to-server/SKILL.md` — for adding interactive UI to an existing MCP server's tools +- `plugins/mcp-apps/skills/convert-web-app/SKILL.md` — for turning an existing web app into a hybrid web + MCP App +- `plugins/mcp-apps/skills/add-apps-to-host/SKILL.md` — for building the host side (sandbox page, AppFrame, backend endpoints) that renders MCP Apps in a chat client diff --git a/docs/agent-skills.md b/docs/agent-skills.md index d27ad719d..df436b821 100644 --- a/docs/agent-skills.md +++ b/docs/agent-skills.md @@ -8,12 +8,13 @@ description: Use Agent Skills to build, migrate, and extend MCP Apps with AI cod [Agent Skills](https://agentskills.io/) are instruction sets that guide AI coding agents through tasks. When you invoke a skill, the agent takes the lead — it asks clarifying questions, makes decisions based on your codebase, and executes the work. -This repository provides four skills: +This repository provides five skills: - [**create-mcp-app**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/create-mcp-app/SKILL.md) — scaffolds a new MCP App with an interactive UI - [**migrate-oai-app**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/migrate-oai-app/SKILL.md) — migrates an existing OpenAI App to the MCP Apps SDK - [**add-app-to-server**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/add-app-to-server/SKILL.md) — adds interactive UI to an existing MCP server's tools - [**convert-web-app**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/convert-web-app/SKILL.md) — converts an existing web application into an MCP App +- [**add-apps-to-host**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/add-apps-to-host/SKILL.md) — adds MCP Apps support to a chat client (host): the sandbox page, the AppFrame component and the backend endpoints they need ## Install the Skills @@ -55,7 +56,7 @@ Then copy the skills from `plugins/mcp-apps/skills/` to your agent's skills dire ## Verify Installation -Ask your agent "What skills do you have?" — you should see `create-mcp-app`, `migrate-oai-app`, `add-app-to-server`, and `convert-web-app` among the available skills. +Ask your agent "What skills do you have?" — you should see `create-mcp-app`, `migrate-oai-app`, `add-app-to-server`, `convert-web-app`, and `add-apps-to-host` among the available skills. ## Invoke a Skill @@ -65,6 +66,7 @@ Try invoking the skills by asking your agent: - "Migrate from OpenAI Apps SDK" — converts an existing OpenAI App to use the MCP Apps SDK - "Add UI to my MCP server" — adds interactive UI to an existing MCP server's tools - "Convert my web app to an MCP App" — converts an existing web application into an MCP App +- "Render MCP Apps in my chat app" — builds the host side: sandbox page, AppFrame and backend endpoints The agent will guide you through the process, asking clarifying questions as needed. diff --git a/docs/building-a-host.html b/docs/building-a-host.html new file mode 100644 index 000000000..d4061600d --- /dev/null +++ b/docs/building-a-host.html @@ -0,0 +1,2008 @@ + + + + + + +Building an MCP Apps Host + + + + + + + +
+ + +
+ +
+

You already have a chat app

+

The four pieces you build

+

You have a chat window, a backend and an AI model that can call tools. To show MCP Apps, you extend two things you already have and add two new ones. The SDK handles the hard protocol work.

+
+ + The four pieces of an MCP Apps host + In the person's browser: your chat UI and AppFrame on your own origin, and the sandbox page on another origin. The chat UI renders an AppFrame, which talks to the sandbox page by postMessage and fetches the app's HTML from your backend. Your backend streams tokens and app-start events to the chat UI and talks MCP to the servers. + + + + + BROWSER + + + YOUR ORIGIN + + + ANOTHER ORIGIN + + + + YOUR SERVER + + + + + + + + + RENDERS + + POSTMESSAGE + + FETCH HTML + CSP + + TOKENS + APP-START + + MCP + + + + 4 + Chat UI + logic + messages, model turns + + + + 3 + AppFrame + one AppBridge per screen + + + + 2 + Sandbox page + holds the app's UI + + + + 1 + Backend + MCP clients + proxy + + + + MCP servers + tools + ui:// screens + +
Orange pieces are new; white ones extend what you have. The small numbers match the sections below. The sandbox page runs in the person's browser like your chat does, but it is served from a different origin, so the browser keeps the two apart. The MCP servers are not yours; you only connect to them.
+
+
+

Piece 1 · extend

Backend

Connects to MCP servers, hides tools the AI shouldn't see, tells the browser "this tool has a screen", and forwards the app's requests.

+

Piece 2 · new

Sandbox page

One tiny HTML page on a separate domain. It holds the app in a sealed frame and passes notes through.

+

Piece 3 · new

AppFrame

A component in your chat bubble. It creates the iframe and an AppBridge, then runs the startup steps in order.

+

Piece 4 · extend

Chat logic

Lets the app write into the chat and tell the AI what it is showing.

+
+
+ + +
+

Know your guest

+

An MCP App has two halves

+

The app's author writes both halves of an MCP App, usually in one project, but the halves run in different places. The server half runs on a server. The UI half is stored on that server and runs in the person's browser, inside your sandbox.

+
+ + The two halves of an MCP App + Left, what the app's author writes: the server half (server.ts) and the UI half (mcp-app.html and its script). Right, where they run. server.ts runs on a server as the MCP App's server half, which also serves the bundled UI as a ui:// resource. Your host carries that HTML to the browser, where it runs inside your sandbox as the MCP App's UI. + + + + + WHAT THE AUTHOR WRITES + + WHERE IT RUNS + + + + SOURCE CODE + + + ON A SERVER + + + IN THE BROWSER + + + + + YOUR SANDBOX + + + + + + RUNS AS + BUNDLED + SERVES + VIA HOST + + SERVER HALF + + server.ts + tool + ui:// resource + UI HALF + + mcp-app.html + .ts + new App(...) + + + MCP App · server + does the tool work + + ui:// resource + the HTML, as text + + The same HTML, now + running like a web page. + + MCP App · UI + draws, answers clicks + +
It works like any website: the HTML file lives on a server, but the page runs in your browser. File names come from examples/basic-server-vanillajs.
+
+
+
+

Server half · server.ts

+

A tool and a screen, tied by one URI

+
registerAppTool(server, "get-time", {
+  inputSchema: z.object({}),
+  _meta: { ui: { resourceUri: "ui://get-time/mcp-app.html" } },
+}, async () => ({
+  content: [{ type: "text", text: time }],
+  structuredContent: { time },
+}));
+
+registerAppResource(server, uri, uri,
+  { mimeType: RESOURCE_MIME_TYPE },
+  async () => ({ contents: [{ uri,
+    mimeType: RESOURCE_MIME_TYPE,
+    text: await readFile("dist/mcp-app.html") }] }));
+
+
+

UI half · src/mcp-app.ts

+

Waits for your host, then draws

+
const app = new App({ name: "Get Time App", version: "1.0.0" });
+
+// register handlers before connect()
+app.ontoolinput  = (p) => showLoading(p.arguments);
+app.ontoolresult = (r) => show(r.structuredContent);
+app.onhostcontextchanged = applyTheme;
+app.onteardown   = async () => { save(); return {}; };
+
+button.onclick = () =>
+  app.callServerTool({ name: "get-time", arguments: {} });
+
+await app.connect();  // sends ui/initialize to your AppFrame
+
+
+
+

Text and data

A tool result has content (text the model reads) and structuredContent (data the UI draws). Pass the whole result to the app.

+

Text first

The server half calls getUiCapability() on your client's capabilities. If your host didn't advertise the extension, it may register a text-only tool instead.

+

React too

React apps use useApp(), useHostStyles() and useAutoResize() from /react. On the wire it's the same protocol.

+
+

You build the host. The app's author builds both halves. You only meet the UI half, through postMessage.

+
+ + +
+

Piece 1

+

Backend: notice the screen

+

Your AI loop already calls tools. Now it checks one extra thing: does this tool come with a screen? If yes, it tells the browser.

+
+ + What the backend does when the model calls a tool + When the model calls a tool, the backend checks for _meta.ui.resourceUri. If present it streams app-start to the browser, then app-result when the call finishes. If absent, the tool result is shown as plain text. + + + + + + YES + NO + + + Model calls a tool + your AI loop + + Has a screen? + _meta.ui.resourceUri + + Send app-start + tool, args, uri + + Send app-result + when tools/call ends + + Plain text, as today + +
+ +

Four jobs

+
+
+

Job 1 · connect

+

Say you support apps

+

When your MCP client connects, advertise the extension. Then list tools and resources once and keep them.

+
capabilities: { extensions: {
+  "io.modelcontextprotocol/ui": {
+    mimeTypes: ["text/html;profile=mcp-app"]
+  } } }
+
+
+

Job 2 · filter

+

Hide app-only tools from the AI

+

If a tool's _meta.ui.visibility leaves out "model", don't give it to the model. It is a button for the app, like "refresh".

+

Helpers: isToolVisibilityAppOnly(tool) and getToolUiResourceUri(tool) from @modelcontextprotocol/ext-apps/app-bridge.

+
+
+

Job 3 · stream

+

Tell the browser

+
    +
  • app-starttoolCallId, server, toolName, args, resourceUri
  • +
  • app-args-partialoptional, while the model is still typing the arguments
  • +
  • app-result or app-cancelledwhen the tool call finishes or fails
  • +
+
+
+

Job 4 · proxy

+

Endpoints for the app

+
    +
  • GET /api/apps/resourcereads the ui:// resource, checks the MIME type, returns { html, csp, permissions }
  • +
  • POST /api/apps/tools/callforwards, but refuses tools whose visibility leaves out "app"
  • +
  • POST /api/apps/resources/readforwards as is
  • +
+
+
+

Also save toolName, args, uri and result with the message, so the app can be redrawn when the chat is reopened.

+
+ + +
+

Piece 2

+

A separate home for strangers

+

The app's HTML was written by someone else. If it ran on your domain, it could read your cookies and your chat. So it runs on a different domain, inside a glass room.

+
+ + Your site, the sandbox origin and the app + Your chat site contains an iframe on a separate sandbox domain, which contains an inner iframe running the app's HTML under a CSP sent as an HTTP header. + + + + YOURAPP.COM · YOUR CHAT + Holds AppBridge, the chat and the login. + + + + SANDBOX.YOURAPP-USERCONTENT.COM + sandbox.html: checks origins, passes notes. + + + + INNER IFRAME · THE APP'S HTML + The MCP App + Can only reach the domains listed in its ui.csp. + CSP is an HTTP header from your sandbox server, so the app can't change it + +
For local work a second port counts as a second origin: the reference host uses 8080 for the chat and 8081 for the sandbox.
+
+

What sandbox.html does, about 130 lines

+
    +
  1. Refuses to run unless it is inside an iframe and the parent's origin is yours.
  2. +
  3. Creates the inner iframe with sandbox="allow-scripts allow-same-origin allow-forms".
  4. +
  5. Tells the parent it is ready: ui/notifications/sandbox-proxy-ready.
  6. +
  7. When ui/notifications/sandbox-resource-ready arrives, writes the HTML into the inner iframe and sets its allow permissions.
  8. +
  9. Passes every other note both ways, always naming the exact target origin, never *.
  10. +
+
+

The sandbox server

Serves sandbox.html with a Content-Security-Policy header built from the ?csp= value. Check every domain in it so nobody can sneak in extra rules with ; or quotes.

+

Copy, don't invent

examples/basic-host/src/sandbox.ts and serve.ts already do all of this. Change the allowed origin to your domain.

+
+
+ + +
+

Piece 3

+

Showing the app, step by step

+

Here is the whole trip, from you typing a question, through the model choosing a tool, to a working screen and the model's answer. Press Play to watch it one stage at a time.

+
+
+ + From your question to a working screen + Browser lanes on the left (chat UI, AppFrame, sandbox page, MCP App UI) and server lanes on the right (your backend, the model, the MCP App server). Your backend asks the model, which asks to call the tool. The backend calls the tool and streams app-start; the chat UI mounts an AppFrame, which fetches the HTML, loads the sandbox and hands over the HTML. The UI and AppFrame shake hands, the AppFrame sends tool-input and then tool-result. Finally the backend gives the model the text content of the result and the model's answer appears in the chat. + + + + + IN THE BROWSER + + + ON SERVERS + + + + + + + + + + + + + tool running… + reply at step 19 + + AppBridge ▸ + + + + + Paris weather? + + + + chat + tools + + + + call the tool + + + + + tools/call + + + + app-start + + + + mounts + + + + + GET html + csp + + + + resources/read + + + + ui:// html + + + + html, csp + + + + + load sandbox + + + + proxy-ready + + + + here is html + + + + runs html + + + + + ui/initialize + + + + + host context + + + + + initialized + + + + + + tool-input + + + + + tool result + + + + app-result + + + + passes it on + + + + tool-result + + + + + + content only + + + + answer + + + + answer text + + + connect() + sendSandboxResourceReady() + receives ui/initialize + replies for you + oninitialized fires + sendToolInput() + sendToolResult() + + HOST + You · chat UI + + HOST + AppFrameholds an AppBridge + + HOST + Sandbox page + + VIEW + MCP App · UI + + HOST + Your backend + + AGENT + Model · LLM + + SERVER + MCP App · server + + + + + LEGEND + REQUEST + REPLY + NOTIFICATION · NO REPLY + YOUR OWN HTTP / CHAT STREAM + PASSED ON BY THE SANDBOX PAGE + APPBRIDGE AT WORK INSIDE THE APPFRAME. ORANGE MONO TEXT = THE APPBRIDGE CALL FOR THAT ARROW + +
+ +
+
+ + + + +
    +
    +
    +

    Overview

    +

    One question becomes a screen

    + +

    All 25 arrows are drawn at once. Press Play to watch them one at a time.

    + +
    +
    +
    +

    Left band: what runs in the person's browser. Right band: servers. Any arrow that crosses the gap between the bands goes over the network, and its label sits in that gap. The two MCP App lanes are one app split in two: its server half runs on a server, and its UI half is HTML that the server hands over and the browser runs, like any web page. The tags give each lane's MCP role: HOST is everything you build, including your backend; VIEW is the app's UI; SERVER is the app's MCP server. Filled head: someone waits for an answer. Open head: one-way. Once the app is running, every note passes through the sandbox page untouched.

    + +

    The same stages in code

    +
    import { AppBridge, PostMessageTransport } from "@modelcontextprotocol/ext-apps/app-bridge";
    +
    +async function mountApp(iframe, call, chat) {
    +  // Fetch the screen: HTML + CSP from your backend
    +  const ui = await api.getAppResource(call.server, call.resourceUri);
    +
    +  const bridge = new AppBridge(null, { name: "my-chat", version: "1.0.0" },
    +    { serverTools: {}, serverResources: {}, openLinks: {}, updateModelContext: { text: {} } },
    +    { hostContext: {
    +        theme: currentTheme(), platform: "web", displayMode: "inline",
    +        availableDisplayModes: ["inline", "fullscreen"],
    +        containerDimensions: { maxHeight: 6000 },
    +        styles: { variables: myCssVariables },
    +    } });
    +
    +  // Register every handler BEFORE connect()
    +  bridge.oncalltool           = (p) => api.callTool(call.server, p);
    +  bridge.onreadresource       = (p) => api.readResource(call.server, p);
    +  bridge.onmessage            = async (p) => { chat.sendAsUser(p); return {}; };
    +  bridge.onupdatemodelcontext = async (p) => { chat.setAppContext(call.toolCallId, p); return {}; };
    +  bridge.onopenlink           = async ({ url }) => { window.open(url, "_blank", "noopener"); return {}; };
    +  bridge.onsizechange         = ({ height }) => { if (height) iframe.style.height = `${height}px`; };
    +  bridge.onrequestdisplaymode = async ({ mode }) => { chat.setFullscreen(call.toolCallId, mode === "fullscreen"); return { mode }; };
    +  const initialized = new Promise((r) => (bridge.oninitialized = () => r()));
    +
    +  // Build the glass room: load sandbox.html?csp=... and wait for proxy-ready
    +  await loadSandboxProxy(iframe, ui.csp, ui.permissions);
    +  // connect: target AND source are this iframe, so other windows are ignored
    +  await bridge.connect(new PostMessageTransport(iframe.contentWindow, iframe.contentWindow));
    +  // ...then hand over the HTML
    +  await bridge.sendSandboxResourceReady({ html: ui.html, csp: ui.csp, permissions: ui.permissions });
    +  // Say hello: AppBridge answers ui/initialize for you
    +  await initialized;
    +  // Send the data
    +  bridge.sendToolInput({ arguments: call.args });
    +  call.result.then((r) => bridge.sendToolResult(r),
    +                   (e) => bridge.sendToolCancelled({ reason: String(e) }));
    +  return bridge;
    +}
    +
    +// When the bubble unmounts
    +await bridge.teardownResource({});   // lets the app save, then remove the iframe
    + +
    +

    Keep it in sync

    Theme changed? bridge.sendHostContextChange({ theme }). Width changed? A ResizeObserver sends containerDimensions.

    +

    Don't talk early

    Send nothing to the app before oninitialized fires. The spec forbids it.

    +

    Copy from

    examples/basic-host/src/implementation.ts has loadSandboxProxy, initializeApp and newAppBridge.

    +
    +
    + + +
    +

    Piece 4

    +

    How the UI and the model stay in touch

    +

    After the first render, the UI can't reach the model directly. Everything goes through your host, by one of four routes, and your host decides what the model gets to see.

    +
    +
    + + Four routes between the UI and the model + Quiet update: the UI sends a model-context update, the host stores only the latest and replies ok; nothing reaches the model until later, when the next turn starts, and then the saved context goes along with that message. Speak up: the UI sends ui/message, the host accepts it, adds it as a new user turn and the model replies in the chat. Own work: the UI calls a tool through the host to the server and the model is not told. Model drives: the host lists the app's own tools, offers them to the model, and runs the model's calls inside the app. + + + + + + + + + ROUTE 1 · QUIET UPDATE + + + ROUTE 2 · SPEAK UP + + + ROUTE 3 · OWN WORK + + + ROUTE 4 · MODEL DRIVES + + + LATER · WHEN THE NEXT TURN STARTS + + + + pans the map + + + + model context + + + + keep latest only + + + + ok + + + + next message + + + + message + context + + + + reply + + + + + taps a button + + + + ui/message + + + + accepted + + + + new user turn + + + + reply + + + + reply in chat + + + + + taps refresh + + + + tools/call + + + + tools/call + + + + result + + + + result + + + + + tools/list + + + + navigate-to, … + + + + + app's tools + + + + call navigate-to + + + + tools/call + + + + result + + + + result + + + PERSON + You + + VIEW + MCP App · UI + + HOST + Your host + + AGENT + Model · LLM + + SERVER + MCP App · server + + + LEGEND + REQUEST + REPLY + WHEN A CONTEXT UPDATE REACHES THE MODEL + TIME PASSES: NOTHING ABOVE THE LINE HAS REACHED THE MODEL + +
    + +
    +
    + + + + +
      +
      +
      +

      Overview

      +

      Four routes, one gatekeeper

      + +

      All four routes are drawn at once. Press Play to watch them one arrow at a time.

      + +
      +
      +
      +

      "Your host" is your chat UI, AppFrame and backend together; the AppBridge inside the AppFrame handles every arrow between the app and your host. The dashed line in route 1 marks time passing: the context update has been saved, but the model hasn't seen it yet.

      + +

      Who picks the route?

      +

      The app's developer, one button at a time. Each click handler calls a different SDK method, each method sends a different message, and AppBridge hands it to a different handler. Your host never guesses.

      +
      + + + + + + + +
      ButtonApp callsYour host getsResult
      RefreshcallServerTooltools/call → oncalltoolThe tool runs on the server. The model isn't involved.
      Explain thissendMessageui/message → onmessageA new user turn starts now.
      (panned the map)updateModelContextui/update-model-context → onupdatemodelcontextSaved for the next turn.
      +
      +

      Your host can't change the route, but it can refuse one: reject the message, block tools without "app" visibility, or leave message or serverTools out of its capabilities.

      + +

      What makes your host list the app's tools? (route 4)

      +
      +

      1 · The handshake

      The app's ui/initialize includes the tools capability. registerTool adds it for you. When oninitialized fires, check bridge.getAppCapabilities()?.tools and call bridge.listTools(). No capability, no route 4.

      +

      2 · The tools change

      If the app declared tools.listChanged, it sends notifications/tools/list_changed whenever it adds, removes or changes a tool. registerTool sends it for you. List again and replace what you offer the model.

      +
      +

      The model and the person never trigger it directly. The model can't ask for tools it hasn't been shown. You can list right away or just before the next model request. Keep one list per screen, keyed by toolCallId, and drop it at teardown.

      + +

      What the model sees, and what it doesn't

      +
      +

      The model sees

        +
      • The tool result's content (text, and images if it has them)
      • +
      • ui/message, as a user message, straight away
      • +
      • The latest updateModelContext, on the next turn
      • +
      • Results of the app's own tools that the model itself called
      • +
      +

      The model never sees

        +
      • The tool result's structuredContent and _meta: those are for the UI
      • +
      • Tools the UI calls with callServerTool, or their results
      • +
      • Logs from sendLog
      • +
      • Clicks, scrolls, typing, anything the app doesn't report
      • +
      • Older context updates that a newer one replaced
      • +
      +
      + +
      + + + + + + + + + + + +
      The app asksYour handlerWhat your host does
      Here is what I showonupdatemodelcontextReplace this app's context slot. Add it to the next model request, whoever starts the turn. Don't start a turn. You may skip duplicates and may show it to the person.
      Say this in the chatonmessageOptionally ask the person. Add it as a user message, reply to the app, and start a model turn. Reply with an error if you refuse.
      Run a tooloncalltoolCheck the tool is on this app's server and includes "app" in its visibility, then forward it. Nothing goes to the model.
      My tools changednotifications/tools/list_changed from the appCall bridge.listTools() again and update what you offer the model.
      Open this linkonopenlinkOpen in a new tab, or confirm first for unknown sites.
      Make me biggeronrequestdisplaymodeMove the iframe to a fullscreen panel, and reply with the mode you actually chose.
      I changed sizeonsizechangeSet the iframe height. No reply needed.
      +
      +
      +

      Keep it small

      Context costs tokens. Apps send short markdown, often with YAML frontmatter. map-server adds a screenshot only if your host declares updateModelContext.image, scaled to 768 px.

      +

      Latest wins

      If several updates arrive before the next user message, send only the last one. An empty update can clear the slot, as basic-host does.

      +

      Many apps, many slots

      Keep one slot per app instance (use toolInfo.id) and label each one, so the model knows which map moved.

      +
      +

      Rule of thumb: updateModelContext says "here is what I'm showing". sendMessage says "please do something now".

      +
      + + +
      +

      State

      +

      Where state lives

      +

      State sits in six places, owned by three parties. Knowing which is which answers most "why did it forget?" questions.

      +
      + + The six places state lives + In the sandbox, the UI keeps view memory and saves to localStorage under the viewUUID. Your host keeps the conversation, one model-context slot per app, and the host context; it replays the conversation into the UI, receives context updates and pushes host context. On the servers, the MCP App keeps server state, reached through app-only tools, and the model reads the conversation every turn and the context slot on the next turn. + + + + SANDBOX · THE UI + + + YOUR HOST + + + SERVERS + + + + + + + + + + SAVE + APP-ONLY TOOLS + through your host + REPLAY + UPDATE + PUSH + EVERY TURN + NEXT TURN + + + View memory + JS variables · gone on reload + + localStorage + key: viewUUID + + + Conversation + tool input, result, messages + + Model context + latest update, per app + + Host context + theme, size, display mode + + + Server state + database, files + + Model · LLM + reads both, each turn + +
      Grey boxes keep their contents; the white one forgets on reload. The orange path is the one UI changes take to reach the model.
      +
      + +
      + + + + + + + + + + +
      StateOwnerSurvives a reload?Model sees it?How it's written and read
      View memoryUINo, the iframe is newNoPlain variables or React state
      localStorageUIYes, if your sandbox origin stays the sameNolocalStorage, keyed by result._meta.viewUUID
      Server stateApp serverYesOnly through tool resultsApp-only tools via callServerTool, scoped by viewUUID or user
      ConversationYour hostYes, you store itcontent yes; structuredContent and _meta noTool calls, tool results, ui/message
      Model contextYour hostOnly if you store itYes, on the next turnupdateModelContext, latest wins
      Host contextYour hostRebuilt each timeNohostContext at start, then sendHostContextChange
      +
      + +

      A screen's life

      +
      + + The life of one MCP App screen + A screen goes from loading to saying hello, to having input (with optional partial input), to showing the result, where the person interacts, and finally is torn down. If the tool call is cancelled it goes to cancelled and then torn down. + + + + + + + + + + PARTIAL 0..N + YOU INTERACT + + + Loading + HTML into sandbox + + Saying hello + ui/initialize + + Has input + tool-input + + Showing result + tool-result + + Torn down + resource-teardown + + Cancelled + tool-cancelled + Teardown can arrive in any state, and the app can ask for it with requestTeardown. + +
      + +

      When the chat is reopened

      +
        +
      1. Load the saved message: tool name, arguments, result and resourceUri, plus the latest model context if you keep it.
      2. +
      3. Mount a fresh AppFrame and sandbox, and get the HTML again (a cache is fine; the HTML is declared up front).
      4. +
      5. Handshake as usual, then send tool-input and tool-result from the saved copy. Replaying avoids running the tool, and its side effects, twice.
      6. +
      7. The app reads _meta.viewUUID from the result and restores the rest from localStorage or its server.
      8. +
      +
      No widget state. OpenAI's Apps SDK has setWidgetState. MCP Apps doesn't: use localStorage, server-side state through app-only tools, and updateModelContext. The spec lists state persistence and restoration as future work.
      +
      + + +
      +

      Reference

      +

      Every message, both directions

      +

      For each thing the app can ask, you declare a capability and write a handler. If you leave a capability out, the app can see it's missing and hide that feature.

      + +

      The app asks, your host answers

      +
      + + + + + + + + + + + + + + + + +
      App callsMessageYour AppBridge handlerDeclare
      callServerTooltools/calloncalltoolserverTools
      readServerResourceresources/readonreadresourceserverResources
      listServerResourcesresources/listonlistresourcesserverResources
      sendMessageui/messageonmessagemessage
      updateModelContextui/update-model-contextonupdatemodelcontextupdateModelContext
      openLinkui/open-linkonopenlinkopenLinks
      downloadFileui/download-fileondownloadfiledownloadFile
      requestDisplayModeui/request-display-modeonrequestdisplaymodeavailableDisplayModes in host context
      sendSizeChanged, automaticui/notifications/size-changedonsizechangenone
      sendLognotifications/messageonloggingmessagelogging
      requestTeardownui/notifications/request-teardownonrequestteardownnone
      createSamplingMessagesampling/createMessageoncreatesamplingmessagesampling
      +
      + +

      Your host tells, the app listens

      +
      + + + + + + + + + + + +
      You callMessageApp handlerWhen
      sendToolInputPartialui/notifications/tool-input-partialontoolinputpartialWhile the model is still typing arguments. Optional.
      sendToolInputui/notifications/tool-inputontoolinputRight after the handshake. Required.
      sendToolResultui/notifications/tool-resultontoolresultWhen the tool call finishes.
      sendToolCancelledui/notifications/tool-cancelledontoolcancelledWhen the call fails or the person stops it.
      sendHostContextChangeui/notifications/host-context-changedonhostcontextchangedTheme, size or display mode changed.
      teardownResourceui/resource-teardownonteardownBefore you remove the iframe.
      callTool, listToolstools/call, tools/listoncalltool, onlisttoolsOnly if the app declared its own tools, so your model can operate the app.
      +
      +
      +

      Free forwarding

      Pass an MCP Client to new AppBridge(client, …) and it fills in oncalltool, onreadresource, onlistresources and the list-changed notices for you. Pass null and you write them, forwarding each request to your backend. This page does the second, because your backend already holds the MCP clients; basic-host does the first. Either way, check that a tool includes "app" in its visibility before running it: the automatic forwarding doesn't.

      +

      Register before connect

      Set every on… handler before bridge.connect(). The app may send requests right after the handshake, and a late handler misses them.

      +
      +
      + + +
      +

      Piece 3, continued

      +

      What you tell the app about its surroundings

      +

      When the app says hello, you answer with host context: a card describing where it lives. When something changes later, send just the changed fields with sendHostContextChange.

      +
      +

      Look

      Match your chat

        +
      • theme"light" or "dark"
      • +
      • styles.variablesyour CSS variables, like --color-background-primary and --font-sans
      • +
      • styles.css.fontsCSS that loads your fonts
      • +
      +

      Space

      Where it can draw

        +
      • displayMode, availableDisplayModesinline, fullscreen, pip
      • +
      • containerDimensionsfixed height or flexible maxHeight, see below
      • +
      • safeAreaInsetspadding to stay clear of notches and system bars
      • +
      +

      Place

      Who is looking

        +
      • locale, timeZonefor dates, numbers and text
      • +
      • platform"web", "desktop" or "mobile"
      • +
      • deviceCapabilities{ touch, hover }
      • +
      • userAgentyour app's name and version
      • +
      +

      Call

      Which call this is

        +
      • toolInfo{ id, tool }: the tool call this screen belongs to, so one app can tell its instances apart
      • +
      +
      +
      + + Fixed versus flexible container size + With a fixed height the host picks the size and the app scrolls inside. With a flexible maxHeight the app reports its size and the host grows the iframe to fit. + + FIXED · { height: 400 } + + + App fills the box + and scrolls inside it + Your host picks the height. + + FLEXIBLE · { maxHeight: 6000 } + + + App reports its size + ui/notifications/size-changed + + your host grows the iframe + The app picks the height, up to your limit. + +
      +

      Width works the same way, with width or maxWidth. Apps report size automatically by default, so in flexible mode set the iframe height in onsizechange and watch for resize loops if your iframe has a border.

      +
      + + +
      +

      Safety

      +

      Permissions, CSP and sign-in

      +

      The server half says what its UI needs. Your host decides what to allow and enforces it in the sandbox.

      +
      + + + + + + + + + + +
      The app asks forField in _meta.uiWhat your host does
      Call an APIcsp.connectDomainsAdds them to connect-src for fetch, XHR and WebSocket
      Load scripts, styles, images, fontscsp.resourceDomainsAdds them to script-src, style-src, img-src, font-src
      Embed another sitecsp.frameDomainsAdds them to frame-src. Without it: frame-src 'none'
      Use a <base> URLcsp.baseUriDomainsAdds them to base-uri. Without it: base-uri 'self'
      Camera, microphone, location, clipboardpermissions.camera, .microphone, .geolocation, .clipboardWriteMay set the inner iframe's allow attribute: buildAllowAttribute(permissions)
      A fixed web address, so an API can allowlist it (CORS)domainServes the sandbox from that origin. The format is up to each host.
      +
      +
      +

      Where to look

      These fields sit in contents[] of the resources/read result. If they're missing there, fall back to the resources/list entry.

      +

      Say what you allowed

      Report what you approved in hostCapabilities.sandbox (csp, permissions) so the app can adapt.

      +

      Nothing listed

      No CSP in _meta means strict defaults: the app can't reach any network address.

      +
      + +

      Signing in halfway through

      +

      An app can start with public data and ask for sign-in only when you press a protected button. The app just calls a tool. Your host handles the rest.

      +
      + + Sign-in when a protected tool is called + The UI calls a tool through the AppFrame and your backend. The server answers HTTP 401, your host runs the OAuth sign-in with the person, retries the call with the token, and the result flows back to the UI. + + + + + + + + + + + + + + + + + tools/call + tools/call + tools/call + HTTP 401 + sign in (OAuth) + retry + token + result + result + result + + MCP App · UI + AppFrame + Your backend + MCP App · server + + + LEGEND + REQUEST + REPLY + YOUR OWN HTTP + +
      The server answers 401 with a WWW-Authenticate header. The person sees your sign-in window, and the app only ever sees a slow tool call that succeeds. Try it with examples/lazy-auth-server.
      +
      +
      + + +
      +

      Real apps

      +

      Patterns your host must handle

      +

      These come from the patterns guide and the example apps. Each one needs a little support from your host.

      +
      +

      pdf-server · system-monitor-server

      Buttons that call hidden tools

      Tools with visibility: ["app"] power refresh buttons, polling and paging. Let them through oncalltool, and keep them out of the model's tool list.

      +

      pdf-server

      Big files in pieces

      If you cap tool-result size, apps fetch large files in chunks through an app-only tool. Don't rate-limit those repeated calls away.

      +

      shadertoy-server · threejs-server

      Streaming arguments

      Send tool-input-partial while the model types. Close any open brackets first so it parses ("healed" JSON). Apps use it for previews only.

      +

      transcript-server

      Big follow-ups

      The app sends a long text through updateModelContext, then a short prompt through sendMessage. Store the context before you start the model turn.

      +

      pdf-server · map-server

      Remembering where you were

      A tool result can carry _meta.viewUUID, and the app saves state in localStorage under it. Keep your sandbox origin stable, and send the same saved result when you redraw the chat.

      +

      any app

      Errors

      The server half returns isError: true and the model reads it. The UI reports problems found later through updateModelContext.

      +

      shadertoy-server · threejs-server

      Offscreen apps

      Heavy apps pause themselves with IntersectionObserver. In long chats you can also tear down apps that scrolled far away.

      +

      debug-server

      Close, download, ask the model

      requestTeardown asks you to close it, so call teardownResource if you agree. downloadFile exists because the sandbox blocks downloads. createSamplingMessage asks your model directly, only if you declare sampling.

      +
      +
      + + +
      +

      Test yourself

      +

      Questions an expert can answer

      +

      These are the questions to ask when you build both an app and a host. If you can answer them all, you understand MCP Apps from both sides.

      +
      +
      +

      Rendering

      +
      +
      Where does the HTML come from, and when should I fetch it?
      +
      From the app server's ui:// resource via resources/read. Resources are declared up front, so you may fetch and cache them when you connect. Data arrives later, as tool input and result.
      +
      Do I need the SDK?
      +
      No. It's JSON-RPC 2.0 over postMessage. App and AppBridge save you the bookkeeping and type checking.
      +
      Why two iframes?
      +
      On the web, the app must run on a different origin from your chat so it can't read your cookies or page. The middle sandbox page provides that origin and passes messages through. Desktop hosts may use one sandboxed frame.
      +
      Can two copies of the same app be on screen?
      +
      Yes, one per tool call, each with its own iframe and AppBridge. toolInfo.id and viewUUID tell them apart. Apps can't talk to each other; the spec lists that as future work.
      +
      What if a host doesn't support MCP Apps?
      +
      The tool still works and the person sees its content as text. Servers can check getUiCapability() and register a text-only tool instead.
      +
      +
      +
      +

      The model

      +
      +
      What does the model see from a tool result?
      +
      content only. structuredContent and _meta are for the UI.
      +
      How does the model learn what I did in the UI?
      +
      Only if the app tells it: updateModelContext (quiet, next turn, latest wins) or sendMessage (a user message, now). The app's own tool calls stay invisible.
      +
      Can the model operate the UI?
      +
      Yes, if the app registers tools with app.registerTool() and your host offers them to the model through bridge.listTools() and bridge.callTool().
      +
      Can the app call the model directly?
      +
      With createSamplingMessage, if you declare sampling and handle oncreatesamplingmessage.
      +
      Can the app see the chat?
      +
      No. It only gets what you send: tool input and result, host context, and replies to its own requests.
      +
      +
      +
      +

      State

      +
      +
      What happens when the chat reloads?
      +
      The iframe is new and its memory is gone. You mount it again and replay the saved input and result; the app restores the rest from localStorage or its server.
      +
      Should I save model context?
      +
      You should give the latest one to the model on future turns. Saving it with the conversation keeps it across reloads. That part is your choice.
      +
      Where should the app keep work the person can't lose?
      +
      On its server, through app-only tools, scoped by viewUUID or user. localStorage suits small view details like page number or camera position.
      +
      +
      +
      +

      Safety and operations

      +
      +
      Can an app call any tool?
      +
      Only tools on its own server whose visibility includes "app". You must reject others, and calls across servers are always blocked for app-only tools.
      +
      Can an app reach the internet?
      +
      Only the domains in its _meta.ui.csp. With no CSP it gets strict defaults and can't reach anything.
      +
      How do I debug?
      +
      Run examples/basic-host: it has Tool Input, Tool Result, Messages and Model Context panels, and logs [HOST] lines in the console. debug-server exercises every capability.
      +
      I have an OpenAI Apps SDK app. Now what?
      +
      docs/migrate_from_openai_apps.md maps window.openai to App methods. The migrate-oai-app skill in plugins/mcp-apps walks through it.
      +
      +
      +
      +
      + + +
      +

      Plan the work

      +

      Build it in this order

      +

      Each step gives you something you can see working before you start the next one.

      +
      + + Suggested build order + First backend events, then the sandbox origin, then showing the app, then talking back, then polish. + + + + + + + 01 + Backend events + extension, app-start + + 02 + Sandbox origin + relay, CSP header + + 03 + Show the app + input, result, size + + 04 + Talk back + message, context + + 05 + Polish + fullscreen, reload + +
      +
        +
      1. Backend events. Connect with the extension, filter tools, stream app-start and app-result. Log them; no UI yet.
      2. +
      3. Sandbox origin. Serve sandbox.html on a second port or domain with the CSP header.
      4. +
      5. Show the app. AppFrame with tool input, tool result and resizing. Test with the examples/basic-server-* servers; npm start in this repo runs them all.
      6. +
      7. Talk back. Add onmessage, onupdatemodelcontext, onopenlink and theme changes.
      8. +
      9. Polish. Fullscreen and picture-in-picture, teardown, redrawing apps from saved chats, permission prompts, and tearing down iframes that scroll far away.
      10. +
      +
      + + +
      +

      Before you ship

      +

      Checklist

      +

      "Must" items come from the spec. "Should" items are what makes it feel finished.

      +
      + + + + + + + + + + + + + + + + + + + + + + + + +
      ItemWhereLevel
      Sandbox page on a different origin from the chatSandboxMust
      Sandbox has allow-scripts and allow-same-originSandboxMust
      CSP built from the resource's ui.csp, strict when missingSandbox serverMust
      Nothing sent to the app before initializedAppFrameMust
      tool-input sent after the handshakeAppFrameMust
      App-only tools hidden from the modelBackendMust
      Model-only tools refused when the app calls themBackendMust
      Advertise io.modelcontextprotocol/ui on connectBackendMust
      teardownResource before removing an iframeAppFrameShould
      Theme and width changes sent with sendHostContextChangeAppFrameShould
      Your CSS variables passed in hostContext.stylesAppFrameShould
      Apps redrawn from saved chat historyBackend + chatShould
      Only declare capabilities you actually handleAppFrameShould
      Partial arguments healed into valid JSON before tool-input-partialBackendShould
      Tool call retried after OAuth when the server answers 401BackendShould
      Inner iframe allow set from permissionsSandboxMay
      One model-context slot per app; only the latest is sent, on the next turnBackend + chatShould
      ui/message added to the conversation as a user turnBackend + chatShould
      Saved tool result replayed on reload instead of calling the tool againChatShould
      App's own tools offered to the model, when the app declares toolsBackend + AppFrameMay
      +
      + +

      Test your host with these example apps

      +

      Run npm start in this repo to serve them all, then connect your host to each one.

      +
      + + + + + + + + + + + + + + +
      ExampleWhat it exercises in your host
      basic-server-*Handshake, tool input and result, messages, links, logs, theme
      integration-serverEvery App API; the E2E tests in this repo run against it
      debug-serverEvery capability, callback and result format combination
      system-monitor-serverApp-only tools and polling
      pdf-serverChunked downloads, saved view state, fullscreen
      map-serverCSP with connectDomains and resourceDomains, fullscreen, model context
      shadertoy-serverStreaming partial arguments, fullscreen, pausing offscreen
      transcript-serverMicrophone and clipboard permissions, model context with follow-up messages
      video-resource-serverBinary data through resources/read
      lazy-auth-serverSign-in on 401 and retrying the call
      +
      +
      One gap in the reference host. examples/basic-host connects with a plain new Client(...) and does not advertise the extension. The example servers don't mind, but a strict server may only send UI to clients that advertise it, so add it in your app.
      + +

      Files to read in this repo

      +
      +

      Host side

      src/app-bridge.ts for every on… handler and send… method.

      +

      Reference host

      examples/basic-host/src/implementation.ts, sandbox.ts, serve.ts.

      +

      The rules

      specification/2026-01-26/apps.mdx, sections Sandbox proxy, Lifecycle and Visibility.

      +
      +
      Based on @modelcontextprotocol/ext-apps 2.1.0 · spec 2026-01-26 · extension io.modelcontextprotocol/ui
      +
      +
      +
      + + + + diff --git a/plugins/mcp-apps/README.md b/plugins/mcp-apps/README.md index 541495c72..2c1b2e8f2 100644 --- a/plugins/mcp-apps/README.md +++ b/plugins/mcp-apps/README.md @@ -27,3 +27,10 @@ Invoke skills by asking Claude Code to: - "Migrate from OpenAI Apps SDK" - "Convert OpenAI App to MCP" - "Port from window.openai" + +### Add MCP Apps to a host + +- "Render MCP Apps in my chat app" +- "Build an MCP Apps host" +- "Write an AppFrame and a sandbox proxy page" +- "Use AppBridge to embed MCP App views" diff --git a/plugins/mcp-apps/skills/add-apps-to-host/SKILL.md b/plugins/mcp-apps/skills/add-apps-to-host/SKILL.md new file mode 100644 index 000000000..14f7fc8c2 --- /dev/null +++ b/plugins/mcp-apps/skills/add-apps-to-host/SKILL.md @@ -0,0 +1,214 @@ +--- +name: add-apps-to-host +description: This skill should be used when the user asks to "render MCP Apps in my chat app", "build an MCP Apps host", "add MCP Apps support to my client", "display MCP App views", "write an AppFrame", "create a sandbox proxy page", "embed ui:// resources in my chat", "use AppBridge", or needs to build the browser side of an MCP Apps host (the sandbox page and the AppFrame component) in TypeScript. Provides the architecture, the startup order, the security rules, and copyable TypeScript for the sandbox proxy, the AppFrame, and the backend endpoints they rely on. +--- + +# Add MCP Apps to a Host + +Make an existing chat application (the **host**) render MCP Apps. When the model calls a tool whose definition has `_meta.ui.resourceUri`, the chat shows that tool's interactive UI inline, and the UI can talk back to the chat and to the model. + +This skill covers the **browser side**, written in TypeScript: the **sandbox page** and the **AppFrame** component. It also covers the small **backend contract** they depend on. Writing the app itself (the server half and its UI) is covered by `create-mcp-app` and `add-app-to-server`. + +## How It Works + +A host that supports MCP Apps is made of four pieces. Two are new and two extend what a chat app already has: + +| # | Piece | New or extend | Runs where | Job | +| --- | ------------ | ------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | Backend | extend | your server | Holds the MCP clients, advertises the UI extension, hides app-only tools from the model, streams `app-start` / `app-result` to the browser, and proxies the app's own requests | +| 2 | Sandbox page | **new** | browser, on a **separate origin** | Holds the untrusted app HTML in an inner iframe and relays `postMessage` traffic both ways. Its CSP comes from an HTTP header | +| 3 | AppFrame | **new** | browser, your origin | One per tool call that has a UI. Creates the iframe, fetches the HTML, creates the `AppBridge`, runs the startup steps in order, delivers input and result, and tears everything down | +| 4 | Chat logic | extend | your app | Turns `ui/message` into a new user turn, stores `ui/update-model-context` for the next turn, and (optionally) offers the app's own tools to the model | + +``` + YOUR ORIGIN (chat UI) SANDBOX ORIGIN +┌────────────────────────────┐ postMessage ┌─────────────────────────────┐ +│ AppFrame (your component) │◀────────────▶│ sandbox.html (relay) │ +│ └─ AppBridge (SDK) │ │ └─ inner iframe: the View │ +└─────────────┬──────────────┘ │ App + PostMessageTransport + │ fetch / SSE (your API) └─────────────────────────────┘ +┌─────────────▼──────────────┐ MCP (Streamable HTTP) +│ Backend (holds MCP Clients)│──────────────────────────────▶ MCP App server +└────────────────────────────┘ +``` + +**AppFrame vs AppBridge.** The AppFrame is _your_ component: it decides _when_ things happen (create the iframe, fetch HTML, wait for the sandbox, send the result, tear down). `AppBridge` is the SDK class _inside_ it that speaks the MCP Apps protocol over `postMessage` (answers `ui/initialize`, sends `tool-input` / `tool-result`, routes the app's requests to your `on…` handlers). Think "manager" and "interpreter". + +**Where the MCP client lives.** `examples/basic-host` connects to MCP servers from the browser and passes that `Client` into `new AppBridge(client, …)`, which wires `tools/call`, `resources/*` and list-changed forwarding automatically. Most production chat apps keep MCP clients on the backend instead. Then pass `null` and forward each request to your backend yourself. This skill uses the backend pattern by default; both are valid and the AppFrame code is nearly identical. + +## Getting Reference Code + +Clone the SDK repository for working examples and API documentation: + +```bash +git clone --branch "v$(npm view @modelcontextprotocol/ext-apps version)" --depth 1 https://github.com/modelcontextprotocol/ext-apps.git /tmp/mcp-ext-apps +``` + +| File | What to take from it | +| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `examples/basic-host/src/sandbox.ts` | The complete sandbox relay. Copy it and change the allowed-origin check | +| `examples/basic-host/sandbox.html` | The sandbox page shell (transparent, full-size inner iframe) | +| `examples/basic-host/serve.ts` | Two servers on two ports, and `buildCspHeader()` / `sanitizeCspDomains()` for the sandbox's `Content-Security-Policy` header | +| `examples/basic-host/src/implementation.ts` | `getUiResource()` (MIME check + CSP/permissions lookup), `loadSandboxProxy()`, `initializeApp()`, `newAppBridge()` (all handlers) | +| `examples/basic-host/src/index.tsx` | React `AppIFramePanel` (Strict Mode guard, graceful teardown) and `isToolVisibleToModel()` | +| `src/app-bridge.ts` | `AppBridge` JSDoc: every `on…` handler, `send…` method, `connect()` auto-forwarding, helper functions | +| `src/spec.types.ts` | `McpUiHostCapabilities`, `McpUiHostContext`, `McpUiResourceCsp`, `McpUiResourcePermissions` | +| `specification/2026-01-26/apps.mdx` | The normative rules: sandbox proxy, visibility, lifecycle, `ui/update-model-context`, `ui/message` | +| `docs/building-a-host.html` | Visual, step-by-step explainer of everything below (for humans; open it in a browser) | + +All host-side imports come from `@modelcontextprotocol/ext-apps/app-bridge`: + +```ts +import { + AppBridge, + PostMessageTransport, + RESOURCE_MIME_TYPE, // "text/html;profile=mcp-app" + buildAllowAttribute, // permissions -> iframe `allow` string + getToolUiResourceUri, // tool -> "ui://..." or undefined + isToolVisibilityAppOnly, + McpUiToolMetaSchema, + type McpUiHostContext, + type McpUiResourceCsp, + type McpUiResourcePermissions, + type McpUiSandboxProxyReadyNotification, + type McpUiSandboxResourceReadyNotification, +} from "@modelcontextprotocol/ext-apps/app-bridge"; +``` + +## Step 0: Analyze the Host + +Before writing code, find out (read the codebase; ask only what it can't tell you): + +1. **Frontend framework.** React, Vue, Svelte or plain DOM. The AppFrame reference has a framework-agnostic core plus a React wrapper; adapt the wrapper. +2. **Where MCP clients live.** Backend (default here) or browser (`basic-host` style). +3. **How the backend talks to the browser during a turn.** SSE, WebSocket or a streamed fetch. The AppFrame needs `app-start`, optional `app-args-partial`, and `app-result` / `app-cancelled` events on that channel. +4. **Where a second origin can live.** Production: a dedicated domain such as `sandbox.yourapp-usercontent.com` (a separate registrable domain is best, so it shares no cookies). Development: a second port (`localhost:8081`). +5. **How messages are stored.** Apps must be re-drawn when a chat is reopened, so the tool name, arguments, resource URI and result must be saved with the message. + +## Step 1: Backend Contract + +Full code: [references/backend-contract.md](references/backend-contract.md). + +1. **Advertise the extension** when each MCP client connects: `capabilities.extensions["io.modelcontextprotocol/ui"] = { mimeTypes: ["text/html;profile=mcp-app"] }`. Servers may register text-only tools when it's missing. +2. **Filter the model's tool list.** Drop tools whose `_meta.ui.visibility` doesn't include `"model"` (visibility defaults to `["model", "app"]`). +3. **Stream app events.** When the model calls a tool with `getToolUiResourceUri(tool)`, emit `app-start { toolCallId, serverId, tool, resourceUri, args }`, then `app-result { toolCallId, result }` or `app-cancelled { toolCallId, reason }` when the `tools/call` finishes. If your model streams arguments, emit `app-start` without `args` as soon as the tool name is known, then `app-args-partial` (healed JSON) and a final `app-args`. +4. **Expose three endpoints** for the AppFrame: + - `GET /api/apps/resource?serverId&uri`: `resources/read`, check the MIME type, return `{ html, csp, permissions }`. + - `POST /api/apps/tools/call`: forward, but **reject tools whose visibility excludes `"app"`** (spec MUST). + - `POST /api/apps/resources/read`: forward. +5. **Persist** `{ toolCallId, serverId, toolName, args, resourceUri, result }` with the assistant message. + +## Step 2: Sandbox Page + +Full code: [references/sandbox-proxy.md](references/sandbox-proxy.md). + +The sandbox page is a tiny HTML page served from a **different origin** than the chat. It: + +1. Refuses to run unless it is inside an iframe whose parent origin is on your allow-list. +2. Self-tests isolation: touching `window.top` must throw. +3. Creates the inner iframe with `sandbox="allow-scripts allow-same-origin allow-forms"`. +4. Posts `ui/notifications/sandbox-proxy-ready` to the parent, with the exact parent origin as `targetOrigin`. +5. On `ui/notifications/sandbox-resource-ready { html, sandbox?, csp?, permissions? }`, sets `allow` from `buildAllowAttribute(permissions)` and writes the HTML into the inner iframe (`document.write`, falling back to `srcdoc`). +6. Relays every other message: parent to inner (after checking `event.origin`), inner to parent (after checking `event.source` and origin; always an explicit `targetOrigin`, never `"*"`). + +The server that serves `sandbox.html` builds a `Content-Security-Policy` **HTTP header** from the `?csp=` query parameter (JSON of `McpUiResourceCsp`), sanitizing every domain, and sends `Cache-Control: no-store`. A header can't be removed by the app's HTML; a `` tag could be. + +## Step 3: AppFrame + +Full code: [references/app-frame.md](references/app-frame.md). + +The AppFrame must perform the startup in **exactly this order**: + +| # | Who | Action | +| --- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | AppFrame | Receives `app-start`; fetches `{ html, csp, permissions }` from `GET /api/apps/resource` | +| 2 | AppFrame | `new AppBridge(null, hostInfo, hostCapabilities, { hostContext })`, then registers **every** `on…` handler (before `connect()`, or early requests are missed) | +| 3 | AppFrame | Sets `iframe.sandbox = "allow-scripts allow-same-origin allow-forms"` and `allow`, loads `sandbox.html?csp=`, waits for `ui/notifications/sandbox-proxy-ready` from _that_ iframe's window | +| 4 | AppBridge | `bridge.connect(new PostMessageTransport(iframe.contentWindow, iframe.contentWindow))`. Target **and** source are this iframe, so other windows are ignored | +| 5 | AppBridge | `bridge.sendSandboxResourceReady({ html, csp, permissions })`. The relay writes the HTML into the inner iframe | +| 6 | View, then AppBridge | The View sends `ui/initialize`; `AppBridge` answers with your capabilities and `hostContext`; the View sends `ui/notifications/initialized`, which fires `bridge.oninitialized` | +| 7 | AppBridge | **Only now**: buffered `sendToolInputPartial(...)` (optional), then `sendToolInput({ arguments })` | +| 8 | AppBridge | When the backend's `tools/call` finishes: `sendToolResult(result)`, or `sendToolCancelled({ reason })` on failure | +| 9 | AppBridge | Ongoing: `sendHostContextChange({ theme })`, `({ containerDimensions })`, `({ displayMode })` | +| 10 | AppFrame | On unmount: `await bridge.teardownResource({})` (with a timeout), then `bridge.close()` and remove the iframe | + +Handlers to register (all before `connect()`): + +| Handler | App method | What your host does | +| ----------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| `oncalltool` | `app.callServerTool()` | `POST /api/apps/tools/call` (backend enforces `"app"` visibility) | +| `onreadresource` | `app.readServerResource()` | `POST /api/apps/resources/read` | +| `onmessage` | `app.sendMessage()` | Add as a user message and start a model turn. Return `{}` once accepted (you may ask the user first) | +| `onupdatemodelcontext` | `app.updateModelContext()` | Store per `toolCallId`, overwriting. Attach to the next user turn. Return `{}` | +| `onopenlink` | `app.openLink()` | `window.open(url, "_blank", "noopener,noreferrer")`, ideally after confirmation or an allow-list check | +| `onsizechange` | auto-resize | Set the iframe height (and `min-width`); account for `box-sizing: border-box` borders | +| `onrequestdisplaymode` | `app.requestDisplayMode()` | Switch inline / fullscreen, `sendHostContextChange({ displayMode })`, return `{ mode }` | +| `onrequestteardown` | `app.requestTeardown()` | Optional: close the frame (which calls `teardownResource`) | +| `ondownloadfile` | `app.downloadFile()` | Optional: downloads are blocked inside the sandbox, so the host saves the file | +| `onloggingmessage` | `app.sendLog()` | Optional: forward to your logs | + +Advertise only what you implement in `hostCapabilities` (`openLinks`, `serverTools`, `serverResources`, `updateModelContext`, `message`, `downloadFile`, `logging`, `sandbox`, `sampling`). + +## Step 4: Chat Logic + +There are four routes between the UI and the model. The app's author picks the route per button by choosing an SDK method; your host just has to support each: + +| Route | App calls | Host does | Model sees | +| ------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | +| Quiet update | `updateModelContext(...)` | Store (overwrite) per app instance; reply `{}`. Send only the latest with the **next** user message, including one that came from `ui/message` | Later, with the next turn | +| Speak up | `sendMessage({ role: "user", content })` | Accept, add as a user turn, run the model, show the reply in the chat | Immediately, as a user message | +| Own work | `callServerTool(...)` | Forward via `oncalltool` to the backend, return the result to the app | Nothing | +| Model drives | `registerTool(...)` in the View | After `oninitialized`, if `bridge.getAppCapabilities()?.tools`, call `bridge.listTools({})` and offer those tools to the model; run its calls with `bridge.callTool(...)`. Re-list on `notifications/tools/list_changed` | The app's tools and results | + +Keep one context slot per app instance (key it by `toolCallId`, which also goes in `hostContext.toolInfo.id`) and label it so the model knows which app it describes. An empty update clears the slot. `structuredContent` and `_meta` of tool results are for the UI and should stay out of the model's context. + +## Step 5: Persistence and Re-rendering + +When a saved chat is reopened, render a new AppFrame for each saved app call and replay `sendToolInput({ arguments })` and `sendToolResult(savedResult)` after `oninitialized`. Do **not** call the tool again. Keep the sandbox origin stable across loads: apps keep state in `localStorage` keyed by `_meta.viewUUID` from the tool result, and a changing origin loses it. For long chats, consider tearing down frames that scrolled far out of view. + +## Step 6: Test + +Use this repo's example servers as test fixtures against your host: + +```bash +cd /tmp/mcp-ext-apps && npm install +EXAMPLE=map-server npm start # one example; the server listens on http://localhost:3101/mcp +npm start # all examples on ports 3101+, plus basic-host on :8080 (sandbox :8081) +``` + +Point your backend at those URLs. Good coverage: `map-server` (CSP for tiles, app-registered tools, model context with screenshots), `pdf-server` (app-only tools, chunked reads, `viewUUID` state), `system-monitor-server` (polling app-only tool), `debug-server` (every host API: links, downloads, teardown requests, logging), `shadertoy-server` / `threejs-server` (`tool-input-partial`). Compare behavior with `basic-host` at `http://localhost:8080` when something differs. + +Checklist: + +- [ ] The sandbox page refuses to load top-level and from an origin not on the allow-list. +- [ ] The app renders, resizes, and follows theme changes. +- [ ] Tool input arrives only after `initialized`; the result or cancellation arrives exactly once. +- [ ] An app-only tool runs from a button but never appears in the model's tool list. +- [ ] A tool without `"app"` visibility is rejected when the app calls it. +- [ ] `ui/message` starts a turn; a context update reaches the model with the next turn, latest only. +- [ ] Closing the bubble sends `ui/resource-teardown` and removes the iframe; reopening the chat re-draws from the saved result. +- [ ] Network requests outside `_meta.ui.csp` are blocked (check the browser console). + +## Rules (Spec and Security) + +- The sandbox page MUST be on a **different origin** from the host. A second port counts in development. +- The sandbox relay MUST check origins: messages from the parent must come from an allowed host origin, messages from the inner frame must come from `inner.contentWindow`, and posts to the parent MUST name the exact origin (never `"*"`). +- Build the CSP from `_meta.ui.csp` (content-level from `resources/read`, falling back to the `resources/list` entry), send it as an **HTTP header**, and sanitize every domain (reject `;`, quotes, spaces, newlines). No CSP declared means strict defaults with no network access. +- Check the resource MIME type is `text/html;profile=mcp-app` before rendering. +- The host MUST NOT send anything to the View before `ui/notifications/initialized`. +- The host MUST reject `tools/call` from an app when the tool's visibility doesn't include `"app"`, and MUST NOT offer the model tools whose visibility doesn't include `"model"`. `AppBridge`'s automatic forwarding does **not** check visibility. +- Never pass the user's session cookies or tokens into the iframe. The app reaches its server only through your host. +- Send `ui/resource-teardown` before removing the iframe, and wait (with a timeout) for the reply. + +## Common Mistakes + +| Symptom | Cause | Fix | +| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| Sandbox throws "No referrer" | The host page sends `Referrer-Policy: no-referrer`, so `document.referrer` is empty | Set `referrerpolicy="origin"` on the iframe, or pass the expected host origin another way and validate it | +| `AppBridge is already connected` | React Strict Mode ran the effect twice on the same bridge | Create the iframe and bridge inside the effect and dispose both in the cleanup (see the React wrapper) | +| Console warns that `oncalltool` was replaced | A `Client` was passed to `AppBridge` **and** `oncalltool` was set: `connect()` overwrites it | Pass `null` and forward yourself, or set your handler after `connect()` | +| The app never gets its input | Input was sent before `oninitialized`, or a partial was sent and the final input never was | Buffer partials; send the final `sendToolInput` after `oninitialized` | +| The iframe height keeps growing | `box-sizing: border-box` borders were not added to the requested size | Copy `onsizechange` from `basic-host/src/implementation.ts` | +| The app's `fetch` fails with a CSP error | Missing `connectDomains`, or a cached `sandbox.html` with an old header | Read `_meta.ui.csp`; serve `sandbox.html` with `Cache-Control: no-store` | +| The app forgets its state after reload | The sandbox origin changes between loads | Keep one stable sandbox origin | +| Context updates never reach the model | Stored but not attached, or attached only to typed messages | Attach the latest context to every next user turn, including `ui/message` turns | diff --git a/plugins/mcp-apps/skills/add-apps-to-host/references/app-frame.md b/plugins/mcp-apps/skills/add-apps-to-host/references/app-frame.md new file mode 100644 index 000000000..6e55a3c9d --- /dev/null +++ b/plugins/mcp-apps/skills/add-apps-to-host/references/app-frame.md @@ -0,0 +1,517 @@ +# AppFrame (Piece 3) + +The AppFrame is the component you render inside an assistant message for **each tool call that has a UI**. It owns one iframe (pointing at your sandbox page) and one `AppBridge`. It runs the startup steps in order, delivers the tool's input and result, keeps the app in sync with the chat (theme, width, display mode), and tears everything down. + +Reference implementation: `examples/basic-host/src/implementation.ts` (`loadSandboxProxy`, `initializeApp`, `newAppBridge`) and `AppIFramePanel` in `examples/basic-host/src/index.tsx`. The code below is the same flow, packaged as one framework-agnostic module plus a thin React wrapper, using the backend-held MCP client pattern (`new AppBridge(null, …)`). + +Install (host author): `npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@^2.0.0 zod@^4.2.0` + +## Lifecycle + +``` +mount ─▶ fetch resource ─▶ load sandbox.html?csp=… ─▶ wait proxy-ready + ─▶ bridge.connect(PostMessageTransport) ─▶ sendSandboxResourceReady(html) + ─▶ (View: ui/initialize ⇄ AppBridge answers) ─▶ oninitialized + ─▶ [partials] ─▶ sendToolInput ─▶ … ─▶ sendToolResult | sendToolCancelled + ─▶ host-context changes (theme, width, display mode) while visible +unmount ─▶ teardownResource (wait, with timeout) ─▶ bridge.close() ─▶ iframe.remove() +``` + +Two rules shape the code: + +1. **Register every handler before `connect()`.** The View may send requests right after its handshake. +2. **Send nothing to the View before `oninitialized`.** Input, partials and results that arrive earlier are queued. + +## app-frame.ts (framework-agnostic core) + +```ts +import { + AppBridge, + PostMessageTransport, + buildAllowAttribute, + type McpUiDisplayMode, + type McpUiHostCapabilities, + type McpUiHostContext, + type McpUiMessageRequest, + type McpUiResourceCsp, + type McpUiResourcePermissions, + type McpUiSandboxProxyReadyNotification, + type McpUiUpdateModelContextRequest, +} from "@modelcontextprotocol/ext-apps/app-bridge"; +import type { + CallToolRequest, + CallToolResult, + ReadResourceRequest, + ReadResourceResult, + Tool, +} from "@modelcontextprotocol/client"; + +/** What GET /api/apps/resource returns (see backend-contract.md). */ +export interface AppResource { + html: string; + csp?: McpUiResourceCsp; + permissions?: McpUiResourcePermissions; +} + +/** One tool call that has a UI, as announced by the backend's `app-start`. */ +export interface AppCall { + toolCallId: string; + serverId: string; + tool: Tool; + resourceUri: string; + /** Final arguments, if already known (always known when re-drawing a saved chat). */ + args?: Record; +} + +/** Your backend endpoints. */ +export interface HostApi { + getAppResource(serverId: string, uri: string): Promise; + callTool( + serverId: string, + params: CallToolRequest["params"], + ): Promise; + readResource( + serverId: string, + params: ReadResourceRequest["params"], + ): Promise; +} + +/** Your chat logic (Piece 4). Optional members turn features on. */ +export interface ChatHooks { + /** Route 2: add as a user message and start a model turn. */ + sendAsUser( + toolCallId: string, + message: McpUiMessageRequest["params"], + ): Promise; + /** Route 1: store (overwrite) this app's context; `null` clears it. */ + setAppContext( + toolCallId: string, + context: McpUiUpdateModelContextRequest["params"] | null, + ): void; + /** Route 4: offer these app-provided tools to the model. */ + setAppTools?(toolCallId: string, tools: Tool[]): void; + /** Fullscreen support. */ + setDisplayMode?(toolCallId: string, mode: McpUiDisplayMode): void; + /** The app asked to be closed (`ui/notifications/request-teardown`). */ + requestClose?(toolCallId: string): void; +} + +export interface AppFrameOptions { + container: HTMLElement; + call: AppCall; + api: HostApi; + chat: ChatHooks; + /** e.g. "https://sandbox.example-usercontent.com/sandbox.html" */ + sandboxUrl: string; + hostInfo: { name: string; version: string }; + /** theme, styles, locale, timeZone, platform, … (toolInfo is added for you) */ + hostContext: Omit; + onError?: (error: unknown) => void; +} + +export interface AppFrameHandle { + readonly bridge: AppBridge; + /** Streaming: latest healed partial arguments while the model types. */ + sendArgsPartial(args: Record): void; + /** Final arguments, if they were not in `call.args`. */ + sendArgs(args: Record): void; + sendResult(result: CallToolResult): void; + sendCancelled(reason: string): void; + updateHostContext(patch: Partial): void; + /** Route 4: run a tool the app registered (model asked for it). */ + callAppTool(params: CallToolRequest["params"]): Promise; + /** Graceful teardown, then remove the iframe. Safe to call twice. */ + dispose(): Promise; +} + +const INNER_SANDBOX = "allow-scripts allow-same-origin allow-forms"; +const PROXY_READY: McpUiSandboxProxyReadyNotification["method"] = + "ui/notifications/sandbox-proxy-ready"; + +export function mountAppFrame(opts: AppFrameOptions): AppFrameHandle { + const { container, call, api, chat } = opts; + const id = call.toolCallId; + + let initialized = false; + let disposed = false; + let inputSent = false; + let latestPartial: Record | undefined; + const queue: Array<() => void> = []; // sends waiting for `initialized` + + const whenInitialized = (send: () => void) => { + if (disposed) return; + if (initialized) send(); + else queue.push(send); + }; + + // --- iframe ------------------------------------------------------------- + const iframe = document.createElement("iframe"); + iframe.title = `${call.tool.title ?? call.tool.name} app`; + iframe.referrerPolicy = "origin"; // the sandbox validates document.referrer + iframe.style.cssText = "display:block; width:100%; height:0; border:none;"; + container.appendChild(iframe); + + // --- AppBridge ------------------------------------------------------------ + // Advertise only what you implement. + const capabilities: McpUiHostCapabilities = { + serverTools: {}, + serverResources: {}, + openLinks: {}, + message: { text: {} }, + updateModelContext: { text: {} }, + }; + + const bridge = new AppBridge(null, opts.hostInfo, capabilities, { + hostContext: { + ...opts.hostContext, + toolInfo: { id, tool: call.tool }, + displayMode: "inline", + availableDisplayModes: chat.setDisplayMode + ? ["inline", "fullscreen"] + : ["inline"], + }, + }); + + // Every handler BEFORE connect(). + // Route 3: the app calls its own server. The backend rejects tools whose + // visibility excludes "app" (spec MUST), so no check is needed here. + bridge.oncalltool = (params) => api.callTool(call.serverId, params); + bridge.onreadresource = (params) => api.readResource(call.serverId, params); + + // Route 2: speak up. + bridge.onmessage = async (params) => { + await chat.sendAsUser(id, params); // may ask the user for consent first + return {}; + }; + + // Route 1: quiet update. Store and reply; the model sees it next turn. + bridge.onupdatemodelcontext = async (params) => { + const empty = + !params.content?.length && + !Object.keys(params.structuredContent ?? {}).length; + chat.setAppContext(id, empty ? null : params); + return {}; + }; + + bridge.onopenlink = async ({ url }) => { + const parsed = new URL(url); + if (parsed.protocol !== "https:" && parsed.protocol !== "http:") { + return { isError: true }; + } + window.open(parsed.href, "_blank", "noopener,noreferrer"); + return {}; + }; + + bridge.onsizechange = ({ width, height }) => { + const style = getComputedStyle(iframe); + const borderBox = style.boxSizing === "border-box"; + if (height !== undefined) { + if (borderBox) { + height += + parseFloat(style.borderTopWidth) + + parseFloat(style.borderBottomWidth); + } + iframe.style.height = `${height}px`; + } + if (width !== undefined) { + if (borderBox) { + width += + parseFloat(style.borderLeftWidth) + + parseFloat(style.borderRightWidth); + } + // A floor, not a fixed width, and never wider than the bubble. + iframe.style.minWidth = `min(${width}px, 100%)`; + } + }; + + bridge.onrequestdisplaymode = async ({ mode }) => { + const next: McpUiDisplayMode = + mode === "fullscreen" && chat.setDisplayMode ? "fullscreen" : "inline"; + chat.setDisplayMode?.(id, next); + bridge.sendHostContextChange({ displayMode: next }); + return { mode: next }; + }; + + bridge.onrequestteardown = () => chat.requestClose?.(id); + + bridge.onloggingmessage = (params) => console.debug(`[app ${id}]`, params); + + // Route 4: the app's own tools. Re-list whenever they change. + const syncAppTools = async () => { + if (!chat.setAppTools || !bridge.getAppCapabilities()?.tools) return; + const { tools } = await bridge.listTools({}); + chat.setAppTools(id, tools); + }; + bridge.setNotificationHandler("notifications/tools/list_changed", () => { + void syncAppTools().catch(opts.onError); + }); + + // --- keep the app in sync with the chat ------------------------------------- + // Per spec the host SHOULD tell the View when its container size changes. + let lastWidth = 0; + const sendWidth = () => + bridge.sendHostContextChange({ + containerDimensions: { width: lastWidth, maxHeight: 6000 }, + }); + const resizeObserver = new ResizeObserver(([entry]) => { + const width = Math.round(entry.contentRect.width); + if (width <= 0 || width === lastWidth) return; + lastWidth = width; + if (initialized && !disposed) sendWidth(); + }); + resizeObserver.observe(container); + + bridge.oninitialized = () => { + initialized = true; + if (latestPartial && !inputSent) { + bridge.sendToolInputPartial({ arguments: latestPartial }); + } + for (const send of queue.splice(0)) send(); + if (lastWidth > 0) sendWidth(); + void syncAppTools().catch(opts.onError); + }; + + // --- startup --------------------------------------------------------------- + void (async () => { + const resource = await api.getAppResource(call.serverId, call.resourceUri); + if (disposed) return; + await loadSandbox(iframe, opts.sandboxUrl, resource); + if (disposed) return; + // Target AND source are this iframe: messages from other windows are ignored. + await bridge.connect( + new PostMessageTransport(iframe.contentWindow!, iframe.contentWindow!), + ); + // Goes to the sandbox relay (not the View), so it is allowed before init. + await bridge.sendSandboxResourceReady({ + html: resource.html, + csp: resource.csp, + permissions: resource.permissions, + }); + })().catch((error) => { + if (!disposed) opts.onError?.(error); + }); + + if (call.args) sendArgs(call.args); + + function sendArgs(args: Record) { + if (inputSent) return; + inputSent = true; + whenInitialized(() => bridge.sendToolInput({ arguments: args })); + } + + return { + bridge, + sendArgsPartial(args) { + if (inputSent || disposed) return; + if (initialized) bridge.sendToolInputPartial({ arguments: args }); + else latestPartial = args; // only the latest snapshot matters + }, + sendArgs, + sendResult(result) { + whenInitialized(() => bridge.sendToolResult(result)); + }, + sendCancelled(reason) { + whenInitialized(() => bridge.sendToolCancelled({ reason })); + }, + updateHostContext(patch) { + // Queued until init, then sent as a partial update. + whenInitialized(() => bridge.sendHostContextChange(patch)); + }, + callAppTool(params) { + return bridge.callTool(params); + }, + async dispose() { + if (disposed) return; + disposed = true; + resizeObserver.disconnect(); + try { + if (initialized) { + // Lets the app save state. Don't wait forever. + await bridge.teardownResource({}, { timeout: 3000 }); + } + } catch (error) { + console.warn(`[app ${id}] teardown failed`, error); + } finally { + await bridge.close().catch(() => {}); + iframe.remove(); + } + }, + }; +} + +/** Load sandbox.html?csp=… and resolve when it posts sandbox-proxy-ready. */ +function loadSandbox( + iframe: HTMLIFrameElement, + sandboxUrl: string, + { csp, permissions }: AppResource, + timeoutMs = 10_000, +): Promise { + iframe.setAttribute("sandbox", INNER_SANDBOX); + const allow = buildAllowAttribute(permissions); + if (allow) iframe.setAttribute("allow", allow); + + const url = new URL(sandboxUrl); + if (csp) url.searchParams.set("csp", JSON.stringify(csp)); // becomes an HTTP header + + return new Promise((resolve, reject) => { + const timer = setTimeout(() => { + window.removeEventListener("message", onMessage); + reject(new Error(`Sandbox at ${url.origin} did not become ready`)); + }, timeoutMs); + + function onMessage(event: MessageEvent) { + if (event.source !== iframe.contentWindow) return; + if (event.origin !== url.origin) return; + if (event.data?.method !== PROXY_READY) return; + clearTimeout(timer); + window.removeEventListener("message", onMessage); + resolve(); + } + + window.addEventListener("message", onMessage); + iframe.src = url.href; + }); +} +``` + +Notes: + +- `bridge.setHostContext(full)` diffs against the current context and sends the changes immediately, so it must not run before `oninitialized` either. Prefer `sendHostContextChange(patch)` through the queue, as above. +- `setNotificationHandler` on `AppBridge` throws if the method already has a handler. Register `notifications/tools/list_changed` once per bridge. +- If you pass an MCP `Client` instead of `null` (browser-held clients, as in `basic-host`), `connect()` installs `oncalltool`, `onreadresource`, `onlistresources`, `onlistresourcetemplates`, `onlistprompts` and list-changed relays, **replacing** any you set earlier. That forwarding does not check tool visibility; add the `"app"` check yourself by setting `oncalltool` after `connect()`. + +## React wrapper + +Create the iframe and the bridge **inside** the effect, and dispose both in the cleanup. That makes React Strict Mode's mount, unmount, mount cycle harmless: the first frame is disposed before the second is created. + +```tsx +import { useEffect, useRef } from "react"; +import type { CallToolResult } from "@modelcontextprotocol/client"; +import { + mountAppFrame, + type AppCall, + type AppFrameHandle, + type ChatHooks, + type HostApi, +} from "./app-frame"; + +export interface AppFrameProps { + call: AppCall; + /** Set when the backend sends app-result / app-cancelled (or from history). */ + result?: CallToolResult; + cancelledReason?: string; + /** Latest healed partial arguments while the model streams them. */ + partialArgs?: Record; + theme: "light" | "dark"; + api: HostApi; + chat: ChatHooks; + /** Expose the handle so the chat can route model calls to app tools (route 4). */ + onHandle?: (toolCallId: string, handle: AppFrameHandle | null) => void; +} + +const SANDBOX_URL = import.meta.env.VITE_SANDBOX_URL as string; // e.g. https://sandbox.example-usercontent.com/sandbox.html + +export function AppFrame(props: AppFrameProps) { + const { call, result, cancelledReason, partialArgs, theme, api, chat } = + props; + const containerRef = useRef(null); + const handleRef = useRef(null); + + // Mount once per tool call. + useEffect(() => { + const handle = mountAppFrame({ + container: containerRef.current!, + call, + api, + chat, + sandboxUrl: SANDBOX_URL, + hostInfo: { name: "my-chat", version: "1.0.0" }, + hostContext: { + theme, + platform: "web", + locale: navigator.language, + timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone, + containerDimensions: { maxHeight: 6000 }, + }, + onError: (e) => console.error(`[AppFrame ${call.toolCallId}]`, e), + }); + handleRef.current = handle; + props.onHandle?.(call.toolCallId, handle); + return () => { + props.onHandle?.(call.toolCallId, null); + handleRef.current = null; + void handle.dispose(); + }; + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [call.toolCallId]); + + useEffect(() => { + if (partialArgs) handleRef.current?.sendArgsPartial(partialArgs); + }, [partialArgs]); + + useEffect(() => { + if (call.args) handleRef.current?.sendArgs(call.args); + }, [call.args]); + + useEffect(() => { + if (result) handleRef.current?.sendResult(result); + }, [result]); + + useEffect(() => { + if (cancelledReason) handleRef.current?.sendCancelled(cancelledReason); + }, [cancelledReason]); + + useEffect(() => { + handleRef.current?.updateHostContext({ theme }); + }, [theme]); + + return
      ; +} +``` + +`sendArgs`, `sendResult` and `sendCancelled` are idempotent enough for re-renders only if you pass stable objects. If your state layer recreates the `result` object on every render, guard with a ref (`sentResultRef`) so the app receives it once. + +## Host Context + +The initial `hostContext` is returned to the View in the `ui/initialize` reply; later changes go out with `bridge.sendHostContextChange(patch)` (a partial update). Fields (`McpUiHostContext` in `src/spec.types.ts`): + +| Field | Set it to | +| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | +| `theme` | `"light"` / `"dark"`; send changes when the user toggles | +| `styles.variables`, `styles.css.fonts` | Your CSS variables and font CSS, so the app can match the chat (`basic-host/src/host-styles.ts`) | +| `displayMode`, `availableDisplayModes` | Current mode and the modes you support | +| `containerDimensions` | `{ width, maxHeight }` for flexible height, or `{ width, height }` for fixed | +| `locale`, `timeZone`, `platform`, `deviceCapabilities`, `safeAreaInsets` | What the app needs to format and lay out | +| `toolInfo` | `{ id: toolCallId, tool }`, added by `mountAppFrame` | + +## Streaming Arguments (optional) + +If your model API streams tool-call arguments, mount the AppFrame as soon as the tool name is known (the backend's `app-start` without `args`), then forward each `app-args-partial` to `sendArgsPartial`. Partials must be **valid JSON objects**: close any open strings, arrays and objects before parsing ("healed" JSON). The View uses them for previews only; the final `sendToolInput` is the source of truth. `shadertoy-server` and `threejs-server` are good tests. + +## Re-drawing a Saved Chat + +Render ``. Do not call the tool again. The app receives the same input and result after `oninitialized`, and can restore its view state from `localStorage` (keyed by `_meta.viewUUID` in the result), provided the sandbox origin is unchanged. + +## Model Context Assembly (Piece 4, for reference) + +```ts +import type { McpUiUpdateModelContextRequest } from "@modelcontextprotocol/ext-apps/app-bridge"; + +type ModelContext = McpUiUpdateModelContextRequest["params"]; + +// One slot per app instance, overwritten on each update. +const appContexts = new Map(); + +function buildUserTurn(text: string) { + const blocks = [...appContexts.values()].map(({ label, params }) => ({ + type: "text" as const, + text: `\n${(params.content ?? []) + .filter((c) => c.type === "text") + .map((c) => c.text) + .join("\n")}\n`, + })); + return { role: "user", content: [...blocks, { type: "text", text }] }; +} +``` + +Attach the latest context to the **next** user turn, whether the user typed it or the app sent it with `ui/message`. `structuredContent` from tool results stays with the UI; the model reads `content`. diff --git a/plugins/mcp-apps/skills/add-apps-to-host/references/backend-contract.md b/plugins/mcp-apps/skills/add-apps-to-host/references/backend-contract.md new file mode 100644 index 000000000..0e581e332 --- /dev/null +++ b/plugins/mcp-apps/skills/add-apps-to-host/references/backend-contract.md @@ -0,0 +1,214 @@ +# Backend Contract (Piece 1) + +The AppFrame and the sandbox page need a few things from your backend. This file lists them, with TypeScript (Express) sketches. Adapt the transport (SSE, WebSocket, streamed fetch) and the framework to what your chat app already uses. + +This assumes the **backend holds the MCP clients** (the common production setup). `examples/basic-host` instead connects from the browser and passes the `Client` to `AppBridge`; see the note at the end. + +## 1. Advertise the UI Extension + +Servers check the client's capabilities (`getUiCapability()` on their side) and may register text-only tools if the extension is missing. Advertise it on every MCP client you create: + +```ts +import { + Client, + StreamableHTTPClientTransport, + type Tool, +} from "@modelcontextprotocol/client"; +import { RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/app-bridge"; + +export async function connectMcpServer(url: string) { + const client = new Client( + { name: "my-chat", version: "1.0.0" }, + { + capabilities: { + extensions: { + "io.modelcontextprotocol/ui": { mimeTypes: [RESOURCE_MIME_TYPE] }, + }, + }, + }, + ); + await client.connect(new StreamableHTTPClientTransport(new URL(url))); + + const { tools } = await client.listTools(); + // Listing-level resource metadata is the fallback for CSP/permissions. + const { resources } = client.getServerCapabilities()?.resources + ? await client.listResources() + : { resources: [] }; + + return { + client, + tools: new Map(tools.map((t) => [t.name, t])), + resources: new Map(resources.map((r) => [r.uri, r])), + }; +} +``` + +Re-list when the server sends `notifications/tools/list_changed` / `notifications/resources/list_changed`, and paginate with `cursor` if the server returns `nextCursor`. + +## 2. Respect Tool Visibility + +`_meta.ui.visibility` is an array of `"model"` and `"app"`; it defaults to `["model", "app"]` when omitted. + +```ts +import { McpUiToolMetaSchema } from "@modelcontextprotocol/ext-apps/app-bridge"; + +function visibilityOf(tool: Tool): Array<"model" | "app"> { + const parsed = McpUiToolMetaSchema.safeParse(tool._meta?.ui); + return (parsed.success && parsed.data.visibility) || ["model", "app"]; +} + +/** Offer to the model only these (spec: MUST NOT include the others). */ +export const isVisibleToModel = (tool: Tool) => + visibilityOf(tool).includes("model"); + +/** Accept app-initiated tools/call only for these (spec: MUST reject the others). */ +export const isCallableByApp = (tool: Tool) => + visibilityOf(tool).includes("app"); +``` + +`isToolVisibilityAppOnly(tool)` and `isToolVisibilityModelOnly(tool)` from `@modelcontextprotocol/ext-apps/app-bridge` test the single-value cases. + +## 3. Stream App Events to the Browser + +In the agent loop, when the model calls a tool, check whether it has a UI: + +```ts +import type { CallToolResult, Tool } from "@modelcontextprotocol/client"; +import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge"; + +type ConnectedServer = Awaited>; + +type AppEvent = + | { + type: "app-start"; + toolCallId: string; + serverId: string; + tool: Tool; + resourceUri: string; + args?: Record; // omitted while arguments are still streaming + } + | { + type: "app-args-partial"; + toolCallId: string; + args: Record; + } + | { type: "app-args"; toolCallId: string; args: Record } + | { type: "app-result"; toolCallId: string; result: CallToolResult } + | { type: "app-cancelled"; toolCallId: string; reason: string }; + +async function runToolCall( + emit: (event: AppEvent) => void, + server: ConnectedServer, + serverId: string, + toolCallId: string, + tool: Tool, + args: Record, +) { + const resourceUri = getToolUiResourceUri(tool); // "ui://…" or undefined + if (resourceUri) { + emit({ type: "app-start", toolCallId, serverId, tool, resourceUri, args }); + } + try { + const result = (await server.client.callTool({ + name: tool.name, + arguments: args, + })) as CallToolResult; + if (resourceUri) emit({ type: "app-result", toolCallId, result }); + return result; // the model reads result.content; structuredContent is for the UI + } catch (error) { + if (resourceUri) { + emit({ type: "app-cancelled", toolCallId, reason: String(error) }); + } + throw error; + } +} +``` + +Streaming arguments (optional): emit `app-start` without `args` as soon as the tool name is known, `app-args-partial` with healed (closed-bracket) JSON as tokens arrive, and `app-args` with the final arguments before running the tool. + +## 4. Endpoints for the AppFrame + +All three must authenticate the user and check that `serverId` belongs to them. + +```ts +import express from "express"; +import { RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/app-bridge"; + +// Your own lookup: authenticates the request and returns that user's server. +declare function getServerForUser( + req: express.Request, + serverId: string, +): ConnectedServer; + +const router = express.Router(); +router.use(express.json()); + +// GET /api/apps/resource?serverId=…&uri=ui://… -> { html, csp, permissions } +router.get("/api/apps/resource", async (req, res) => { + const server = getServerForUser(req, String(req.query.serverId)); + const uri = String(req.query.uri); + if (!uri.startsWith("ui://")) + return res.status(400).json({ error: "Not a ui:// URI" }); + + const { contents } = await server.client.readResource({ uri }); + const content = contents[0]; + if (contents.length !== 1 || content.mimeType !== RESOURCE_MIME_TYPE) { + return res + .status(415) + .json({ error: `Unsupported resource: ${content?.mimeType}` }); + } + const html = + "blob" in content + ? Buffer.from(content.blob, "base64").toString("utf8") + : content.text; + + // Content-level _meta.ui wins; fall back to the resources/list entry. + const contentUi = ( + content._meta as { ui?: Record } | undefined + )?.ui; + const listingUi = ( + server.resources.get(uri)?._meta as + | { ui?: Record } + | undefined + )?.ui; + const ui = contentUi ?? listingUi ?? {}; + + res.json({ html, csp: ui.csp, permissions: ui.permissions }); +}); + +// POST /api/apps/tools/call { serverId, params: { name, arguments } } +router.post("/api/apps/tools/call", async (req, res) => { + const server = getServerForUser(req, req.body.serverId); + const tool = server.tools.get(req.body.params?.name); + if (!tool || !isCallableByApp(tool)) { + // Spec MUST: reject app calls to tools whose visibility excludes "app". + return res.status(403).json({ error: "Tool not available to apps" }); + } + res.json(await server.client.callTool(req.body.params)); +}); + +// POST /api/apps/resources/read { serverId, params: { uri } } +router.post("/api/apps/resources/read", async (req, res) => { + const server = getServerForUser(req, req.body.serverId); + res.json(await server.client.readResource(req.body.params)); +}); +``` + +The browser side of these (`HostApi` in `app-frame.md`) is three `fetch` calls. Return errors as HTTP errors and let the `fetch` wrapper throw; `AppBridge` turns a thrown handler error into a JSON-RPC error for the app. + +Don't rate-limit app-only tools too aggressively: apps like `pdf-server` page through large files with many small calls, and `system-monitor-server` polls. + +## 5. Persist What Re-drawing Needs + +Store with the assistant message: `toolCallId`, `serverId`, the tool name (or definition), `args`, `resourceUri`, and the full `CallToolResult` (including `structuredContent` and `_meta`, e.g. `_meta.viewUUID`). When the chat is reopened, the AppFrame replays input and result without calling the tool again. + +## Model-Side Rules (Piece 4 touches the backend too) + +- Build the model's tool list from `isVisibleToModel` tools only. +- Give the model `result.content`. Keep `structuredContent` and `_meta` for the UI. +- Context from `ui/update-model-context` is stored per app instance and attached to the next user turn (latest only). The host MAY defer it; it MUST NOT be lost. +- App-provided tools (route 4) come from the browser (`bridge.listTools`). If your agent loop runs on the backend, the browser must send those tool definitions up with the turn, and the backend must send the model's calls to them back down to the right AppFrame (`handle.callAppTool`) and wait for the result. + +## Browser-Held Clients (the basic-host pattern) + +If the browser connects to MCP servers directly, pass that `Client` to `new AppBridge(client, …)`. `connect()` then forwards `tools/call`, `resources/read`, `resources/list`, `resources/templates/list` and `prompts/list` automatically and relays list-changed notifications. It does **not** check visibility: after `connect()`, replace `oncalltool` with a version that looks up the tool and rejects it unless `isCallableByApp(tool)`. You still need the resource fetch (`client.readResource`) and the MIME check, just without the HTTP hop (see `getUiResource()` in `examples/basic-host/src/implementation.ts`). diff --git a/plugins/mcp-apps/skills/add-apps-to-host/references/sandbox-proxy.md b/plugins/mcp-apps/skills/add-apps-to-host/references/sandbox-proxy.md new file mode 100644 index 000000000..753dd4684 --- /dev/null +++ b/plugins/mcp-apps/skills/add-apps-to-host/references/sandbox-proxy.md @@ -0,0 +1,295 @@ +# Sandbox Page (Piece 2) + +The sandbox page is the "glass room" that holds an MCP App's HTML. The HTML was written by a third party, so it must never run on the chat's origin, where it could read cookies, `localStorage` or the conversation. This page lives on a **second origin** and relays messages between your AppFrame and the app. + +Reference implementation: `examples/basic-host/src/sandbox.ts`, `examples/basic-host/sandbox.html` and the sandbox half of `examples/basic-host/serve.ts`. The code below follows them, with an exact-origin allow-list instead of the `localhost` regex. + +## Two Frames, Two Origins + +``` +https://chat.example.com (host: AppFrame + AppBridge, the user's session) +└─