Skip to main content

Sandbox Proxy Overview

@interopio/mcp-apps-proxy packages the MCP Apps sandbox proxy — per the MCP Apps spec, "Sandbox proxy" section — as an installable <mcp-apps-proxy> web component.

Installation​

npm install @interopio/mcp-apps-proxy

Main API​

Importing the package registers the <mcp-apps-proxy> custom element. Serve a page that imports it and renders the element:

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

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

Host applications (e.g. @interopio/ai-web) keep pointing their existing sandboxProxyUrl at wherever you serve this page — nothing changes on the host side. ?mode=workspace on the URL still selects workspace mode, exactly like a hand-written proxy.

<mcp-apps-proxy> is a plain custom element with no framework dependency, so it works the same way whether the page serving it is vanilla HTML, Angular, or React — see Examples for both.

Workspace Mode io Discovery​

Workspace mode needs an initialized io.Connect instance. Rather than the host page handing one to the element, the element discovers it itself: anything on the page that calls IOBrowser()/IODesktop() makes its io instance discoverable through the window "Glue42" event handshake those factories wire up internally.

import IOBrowser from "@interopio/browser";

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

if (params.get("mode") === "workspace") {
    await IOBrowser();
}

The package has no dependency on @interopio/browser/@interopio/desktop and never calls IOBrowser()/IODesktop() itself, so no io.Connect types need to be pulled in for inline-only consumers. This means:

  • the proxy always reuses whatever io.Connect instance/session your application already initialized — never a second, competing one,
  • inline-only consumers (pages that never call IOBrowser()/IODesktop()) execute zero io.Connect runtime code.
  • Examples for inline and workspace usage, and wiring sandboxProxyUrl on the host
  • Sandbox Proxy for why a sandbox proxy is required and how display modes map to transports
  • The Sandbox Proxy for the full transport and handshake protocol this component implements