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.
+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.
+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.
+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-resultorapp-cancelledwhen the tool call finishes or fails
+
Job 4 · proxy
+Endpoints for the app
+-
+
GET /api/apps/resourcereads theui://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.
+What sandbox.html does, about 130 lines
+-
+
- Refuses to run unless it is inside an iframe and the parent's origin is yours. +
- Creates the inner iframe with
sandbox="allow-scripts allow-same-origin allow-forms".
+ - Tells the parent it is ready:
ui/notifications/sandbox-proxy-ready.
+ - When
ui/notifications/sandbox-resource-readyarrives, writes the HTML into the inner iframe and sets itsallowpermissions.
+ - Passes every other note both ways, always naming the exact target origin, never
*.
+
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.
+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.
+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.
+| Button | App calls | Your host gets | Result |
|---|---|---|---|
| Refresh | callServerTool | tools/call → oncalltool | The tool runs on the server. The model isn't involved. |
| Explain this | sendMessage | ui/message → onmessage | A new user turn starts now. |
| (panned the map) | updateModelContext | ui/update-model-context → onupdatemodelcontext | Saved 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
structuredContentand_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 asks | Your handler | What your host does |
|---|---|---|
| Here is what I show | onupdatemodelcontext | Replace 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 chat | onmessage | Optionally 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 tool | oncalltool | Check the tool is on this app's server and includes "app" in its visibility, then forward it. Nothing goes to the model. |
| My tools changed | notifications/tools/list_changed from the app | Call bridge.listTools() again and update what you offer the model. |
| Open this link | onopenlink | Open in a new tab, or confirm first for unknown sites. |
| Make me bigger | onrequestdisplaymode | Move the iframe to a fullscreen panel, and reply with the mode you actually chose. |
| I changed size | onsizechange | Set 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.
+| State | Owner | Survives a reload? | Model sees it? | How it's written and read |
|---|---|---|---|---|
| View memory | UI | No, the iframe is new | No | Plain variables or React state |
| localStorage | UI | Yes, if your sandbox origin stays the same | No | localStorage, keyed by result._meta.viewUUID |
| Server state | App server | Yes | Only through tool results | App-only tools via callServerTool, scoped by viewUUID or user |
| Conversation | Your host | Yes, you store it | content yes; structuredContent and _meta no | Tool calls, tool results, ui/message |
| Model context | Your host | Only if you store it | Yes, on the next turn | updateModelContext, latest wins |
| Host context | Your host | Rebuilt each time | No | hostContext at start, then sendHostContextChange |
A screen's life
+When the chat is reopened
+-
+
- Load the saved message: tool name, arguments, result and
resourceUri, plus the latest model context if you keep it.
+ - Mount a fresh AppFrame and sandbox, and get the HTML again (a cache is fine; the HTML is declared up front). +
- Handshake as usual, then send
tool-inputandtool-resultfrom the saved copy. Replaying avoids running the tool, and its side effects, twice.
+ - The app reads
_meta.viewUUIDfrom the result and restores the rest fromlocalStorageor its server.
+
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 calls | Message | Your AppBridge handler | Declare |
|---|---|---|---|
callServerTool | tools/call | oncalltool | serverTools |
readServerResource | resources/read | onreadresource | serverResources |
listServerResources | resources/list | onlistresources | serverResources |
sendMessage | ui/message | onmessage | message |
updateModelContext | ui/update-model-context | onupdatemodelcontext | updateModelContext |
openLink | ui/open-link | onopenlink | openLinks |
downloadFile | ui/download-file | ondownloadfile | downloadFile |
requestDisplayMode | ui/request-display-mode | onrequestdisplaymode | availableDisplayModes in host context |
sendSizeChanged, automatic | ui/notifications/size-changed | onsizechange | none |
sendLog | notifications/message | onloggingmessage | logging |
requestTeardown | ui/notifications/request-teardown | onrequestteardown | none |
createSamplingMessage | sampling/createMessage | oncreatesamplingmessage | sampling |
Your host tells, the app listens
+| You call | Message | App handler | When |
|---|---|---|---|
sendToolInputPartial | ui/notifications/tool-input-partial | ontoolinputpartial | While the model is still typing arguments. Optional. |
sendToolInput | ui/notifications/tool-input | ontoolinput | Right after the handshake. Required. |
sendToolResult | ui/notifications/tool-result | ontoolresult | When the tool call finishes. |
sendToolCancelled | ui/notifications/tool-cancelled | ontoolcancelled | When the call fails or the person stops it. |
sendHostContextChange | ui/notifications/host-context-changed | onhostcontextchanged | Theme, size or display mode changed. |
teardownResource | ui/resource-teardown | onteardown | Before you remove the iframe. |
callTool, listTools | tools/call, tools/list | oncalltool, onlisttools | Only 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-primaryand--font-sans
+ styles.css.fontsCSS that loads your fonts
+
Space
Where it can draw
-
+
displayMode,availableDisplayModesinline, fullscreen, pip
+ containerDimensionsfixedheightor flexiblemaxHeight, 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
+
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 for | Field in _meta.ui | What your host does |
|---|---|---|
| Call an API | csp.connectDomains | Adds them to connect-src for fetch, XHR and WebSocket |
| Load scripts, styles, images, fonts | csp.resourceDomains | Adds them to script-src, style-src, img-src, font-src |
| Embed another site | csp.frameDomains | Adds them to frame-src. Without it: frame-src 'none' |
Use a <base> URL | csp.baseUriDomains | Adds them to base-uri. Without it: base-uri 'self' |
| Camera, microphone, location, clipboard | permissions.camera, .microphone, .geolocation, .clipboardWrite | May set the inner iframe's allow attribute: buildAllowAttribute(permissions) |
| A fixed web address, so an API can allowlist it (CORS) | domain | Serves 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.
+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 viaresources/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.AppandAppBridgesave 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.idandviewUUIDtell 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
contentas text. Servers can checkgetUiCapability()and register a text-only tool instead.
+
The model
+-
+
- What does the model see from a tool result? +
contentonly.structuredContentand_metaare 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) orsendMessage(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 throughbridge.listTools()andbridge.callTool().
+ - Can the app call the model directly? +
- With
createSamplingMessage, if you declaresamplingand handleoncreatesamplingmessage.
+ - 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
localStorageor 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
viewUUIDor user.localStoragesuits 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-serverexercises every capability.
+ - I have an OpenAI Apps SDK app. Now what? +
docs/migrate_from_openai_apps.mdmapswindow.openaitoAppmethods. Themigrate-oai-appskill inplugins/mcp-appswalks 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.
+-
+
- Backend events. Connect with the extension, filter tools, stream
app-startandapp-result. Log them; no UI yet.
+ - Sandbox origin. Serve
sandbox.htmlon a second port or domain with the CSP header.
+ - Show the app.
AppFramewith tool input, tool result and resizing. Test with theexamples/basic-server-*servers;npm startin this repo runs them all.
+ - Talk back. Add
onmessage,onupdatemodelcontext,onopenlinkand theme changes.
+ - Polish. Fullscreen and picture-in-picture, teardown, redrawing apps from saved chats, permission prompts, and tearing down iframes that scroll far away. +
Before you ship
+Checklist
+"Must" items come from the spec. "Should" items are what makes it feel finished.
+| Item | Where | Level |
|---|---|---|
| Sandbox page on a different origin from the chat | Sandbox | Must |
Sandbox has allow-scripts and allow-same-origin | Sandbox | Must |
CSP built from the resource's ui.csp, strict when missing | Sandbox server | Must |
Nothing sent to the app before initialized | AppFrame | Must |
tool-input sent after the handshake | AppFrame | Must |
| App-only tools hidden from the model | Backend | Must |
| Model-only tools refused when the app calls them | Backend | Must |
Advertise io.modelcontextprotocol/ui on connect | Backend | Must |
teardownResource before removing an iframe | AppFrame | Should |
Theme and width changes sent with sendHostContextChange | AppFrame | Should |
Your CSS variables passed in hostContext.styles | AppFrame | Should |
| Apps redrawn from saved chat history | Backend + chat | Should |
| Only declare capabilities you actually handle | AppFrame | Should |
Partial arguments healed into valid JSON before tool-input-partial | Backend | Should |
Tool call retried after OAuth when the server answers 401 | Backend | Should |
Inner iframe allow set from permissions | Sandbox | May |
| One model-context slot per app; only the latest is sent, on the next turn | Backend + chat | Should |
ui/message added to the conversation as a user turn | Backend + chat | Should |
| Saved tool result replayed on reload instead of calling the tool again | Chat | Should |
App's own tools offered to the model, when the app declares tools | Backend + AppFrame | May |
Test your host with these example apps
+Run npm start in this repo to serve them all, then connect your host to each one.
| Example | What it exercises in your host |
|---|---|
basic-server-* | Handshake, tool input and result, messages, links, logs, theme |
integration-server | Every App API; the E2E tests in this repo run against it |
debug-server | Every capability, callback and result format combination |
system-monitor-server | App-only tools and polling |
pdf-server | Chunked downloads, saved view state, fullscreen |
map-server | CSP with connectDomains and resourceDomains, fullscreen, model context |
shadertoy-server | Streaming partial arguments, fullscreen, pausing offscreen |
transcript-server | Microphone and clipboard permissions, model context with follow-up messages |
video-resource-server | Binary data through resources/read |
lazy-auth-server | Sign-in on 401 and retrying the call |
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.