Skip to main content

Sandbox Proxy

Every MCP App is an HTML page delivered by the MCP server. Rendering that HTML directly inside your application's own frame would mix untrusted third-party code with your own origin. The sandbox proxy is the piece of infrastructure that prevents this: a small page that sits between your host application and the MCP App HTML, forwarding protocol messages while keeping the untrusted code isolated in its own sandboxed iframe.

Required Infrastructure

Every MCP App host needs a sandbox proxy — @interopio/mcp-apps-proxy is io.Intelligence's ready-made one.

@interopio/ai-web and the ready-made io.Assist apps all expect a sandboxProxyUrl. Install this package instead of hand-writing and maintaining that page yourself.

Why It Exists​

MCP App HTML comes from the MCP server, not your own codebase, so rendering it directly in your application's frame would mix untrusted code with your own origin. The sandbox proxy sits in between: it runs in your trusted frame, loads the actual MCP App HTML into its own sandboxed inner iframe, and relays JSON-RPC messages between the two sides.

The proxy page itself is not sandboxed — only the inner iframe holding the MCP App HTML is. That inner iframe is the real security boundary.

Using the Ready-Made Proxy​

@interopio/mcp-apps-proxy packages this protocol as an installable <mcp-apps-proxy> custom element, so you serve a page that imports it instead of hand-rolling or copy-pasting the implementation:

<script type="module">
    import "@interopio/mcp-apps-proxy";
    import IOBrowser from "@interopio/browser";

    const params = new URLSearchParams(window.location.search);

    if (params.get("mode") === "workspace") {
        await IOBrowser();
    }
</script>

<mcp-apps-proxy></mcp-apps-proxy>

Serve that page anywhere in your application and point your host's sandboxProxyUrl at it:

const aiWeb = await IoAiWebFactory(io, {
    mcp: {
        mcpApps: {
            sandboxProxyUrl: "/sandbox-proxy.html",
            displayMode: "workspace",
        },
    },
});

Nothing changes on the host side — @interopio/mcp-apps-proxy implements the exact same sandboxProxyUrl contract that a hand-written proxy page would.

→ See Sandbox Proxy Package Reference for installation, the workspace-mode io discovery behavior, and both inline and workspace consumption examples.

Inline vs. Workspace Mode​

The same proxy page handles both display modes. The host appends ?mode=workspace to the URL to select which one, and the proxy switches transport accordingly:

  • Inline (default) — relays messages over window.postMessage
  • Workspace — relays messages over io.Connect interop, since postMessage cannot reach across separate windows

You do not configure this yourself; the host decides the display mode and appends the right query parameter.

→ For the full message-by-message protocol — both transports, the startup handshake, and a guide to building your own proxy from scratch — see The Sandbox Proxy in the AI Web examples.

Next Steps​