mcp-apps-web-host
v1.3.1
Published
Dependency-free MCP Apps host for web pages, with a sandbox proxy on a second origin.
Maintainers
Readme
mcp-apps-web-host
Show MCP Apps views in a web page without giving them your page's origin. One ES module for the page and one static page for a sandbox origin; no dependencies, no build step.
It loads a tool's ui:// view through a sandbox proxy on a second origin,
runs the handshake, forwards the tool input, result and host context, routes
ui/message to your handler, and tears the view down cleanly. It implements MCP
Apps 2026-01-26
(specification),
and was extracted from LogiOps AI,
where the same two files render a plan-comparison card.
Install
npm install mcp-apps-web-hostTypeScript declarations ship with the package. Serve the sandbox page (mcp-apps-web-host/sandbox.html, in the package at
sandbox/sandbox.html) as a static file from the sandbox origin. Without npm,
copy src/host.js and sandbox/sandbox.html.
Use
import { createMcpAppHost } from "mcp-apps-web-host";
const host = createMcpAppHost({
sandboxOrigin: "https://sandbox.example.com", // null disables views entirely
hostOrigin: location.origin,
slot: document.getElementById("mcp-app-slot"), // the iframe goes here
mcp: { request: (method, params) => mcpClient.request(method, params) }, // tools/list, resources/read
uriPrefix: "ui://my-server/", // only views under this prefix are loaded
hostInfo: { name: "My host", version: "1.0.0" },
hostContext: () => ({ theme: "dark", displayMode: "inline" }),
onMessage: async (params) => handleViewMessage(params), // true accepts; false, a throw or a rejection refuses
});
await host.show({ toolName: "compare_options", input, result: toolResult });
host.notifyContext(); // after a theme or size change
await host.hide("replaced"); // ui/resource-teardown, then the frame is removedshow finds the tool's _meta.ui.resourceUri, reads the resource once, and
shows it only if its MIME type is text/html;profile=mcp-app. It returns the
resource, or null when nothing was shown: a show that a newer one supersedes,
or whose optional stillWanted() turns false, shows nothing. Other options:
onHide, rejectMessage, frameTitle, frameId, proxyPath, minHeight,
maxHeight, teardownTimeout, readyTimeout, onReady, onError, mime,
protocol and window. The host also has loadResource(toolName) to prefetch,
isShowing(), ready() and destroy().
show() resolves when the iframe is mounted. Keep a fallback visible until
onReady(resource) fires, after the view initializes and receives its tool data.
onError(error) reports iframe load failures or initialization exceeding
readyTimeout, and the failed iframe is removed. The limit is disabled by
default (0); set a positive number of milliseconds to enable it. The budget
restarts once when the sandbox page fires load. Infinity also disables it.
A browser fires load for an error page too, so the timeout is what catches a
sandbox that answers with an HTTP error. Hiding, replacing, or destroying a view
cancels its pending readiness timer; onHide runs for a failed view as well.
Tool discovery follows every nextCursor, and a null or empty one ends the
listing. A missing tool or an unreadable resource is retried on the next request,
a tool that declares no view is cached, and successful reads stay cached.
Serve the sandbox page
Serve sandbox.html from the sandbox origin only; the page's own origin must
answer 404 for it. Locally, two ports or 127.0.0.1 and localhost are two
origins; in production, use a second hostname. Send:
Content-Security-Policy: default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; font-src data:; connect-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors <page origin>
Referrer-Policy: no-referrerThis header caps what any view can ask for in its _meta.ui.csp: with it, a view
can inline scripts, styles, images and fonts, and cannot load or fetch anything.
To let views reach an API, add its origin to connect-src here as well.
Why a second origin
A view is HTML from an MCP server you may not control. In an iframe on your own
origin it could read your page's storage, cookies and DOM. So the page talks only
to a proxy on another origin, the proxy runs the view in a sandboxed inner
iframe under a CSP, and messages cross both boundaries as JSON-RPC over
postMessage.
page origin (your app) sandbox origin (static page only)
┌────────────────────────┐ postMessage ┌──────────────────────────────┐
│ createMcpAppHost(...) │ ──────────────► │ sandbox.html?host=<page> │
│ - reads ui:// via MCP │ ◄────────────── │ inner <iframe sandbox> │
│ - handshake, context │ │ srcdoc = CSP + view HTML │
│ - ui/message handler │ │ forwards JSON-RPC both ways│
└────────────────────────┘ └──────────────────────────────┘Security model
- Origins. The host accepts a message only from the proxy frame's window
and the sandbox origin, and names that origin on everything it posts. The
proxy runs only when it is framed and
?host=names another origin (checked againstancestorOriginswhere the browser reports it; Firefox masks it as"null"behind a no-referrer frame), and forwards only between that host and the current view. - No spoofing. Proxy-level messages (
ui/notifications/sandbox-*) never cross the proxy in either direction. - Sandbox. The view's
sandboxtokens are filtered through an allowlist that never includesallow-same-originorallow-top-navigation, and its CSP is built only from thehttps://origins in_meta.ui.csp. - Narrow surface. Views receive only the
ui/initializeresult,tool-input,tool-resultandhost-context-changed; other requests get-32601.ui/messageis their only way to affect the page, through your handler. Size changes are clamped. - Clean teardown. Hiding sends
ui/resource-teardownand removes the frame on the reply or after a timeout; a view that navigates away is removed and reported. Answers meant for a replaced view are dropped.
Try it
npm run exampleOpens a page on http://127.0.0.1:8000 and the sandbox on
http://127.0.0.1:8001, with a stand-in MCP server that has one tool and one
view. Call the tool, switch the theme, pick an option (the page accepts two of
the three) and hide the view; the page logs what it saw.
Tests
npm test runs two node:test suites with no browser: the host against a fake
window, and the sandbox page's script in node:vm. LogiOps AI's Playwright
suite runs the same two files across two real origins.
License
MIT. Changes are in CHANGELOG.md; how to contribute, in CONTRIBUTING.md.
