feat: add sandbox flags negotiation

.husky/pre-commit

@@ -21,8 +21,10 @@ STAGED=$(git diff --name-only --cached)
 npm run build:all
 npm run prettier:fix
 
-# Re-stage originally-staged files (prettier may have reformatted them)
-echo "$STAGED" | xargs -r git add
+# Re-stage originally-staged files (prettier may have reformatted them).
+# Filter to existing files only — deleted files are already staged for removal
+# and `git add` would fail on them.
+echo "$STAGED" | while IFS= read -r f; do [ -e "$f" ] && git add "$f"; done
 
 # Also stage generated files (regenerated by build:all from spec.types.ts)
 git add src/generated/

examples/basic-host/src/implementation.ts

@@ -1,4 +1,4 @@
-import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport, type McpUiResourceCsp, type McpUiResourcePermissions, buildAllowAttribute, type McpUiUpdateModelContextRequest, type McpUiMessageRequest } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport, type McpUiResourceCsp, type McpUiResourcePermissions, type McpUiResourceSandbox, buildAllowAttribute, buildSandboxAttribute, type McpUiUpdateModelContextRequest, type McpUiMessageRequest } from "@modelcontextprotocol/ext-apps/app-bridge";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
@@ -72,6 +72,7 @@ interface UiResourceData {
   html: string;
   csp?: McpUiResourceCsp;
   permissions?: McpUiResourcePermissions;
+  sandbox?: McpUiResourceSandbox;
 }
 
 export interface ToolCallInfo {
@@ -151,20 +152,25 @@ async function getUiResource(serverInfo: ServerInfo, uri: string): Promise<UiRes
   const uiMeta = contentMeta?.ui ?? listingMeta?.ui;
   const csp = uiMeta?.csp;
   const permissions = uiMeta?.permissions;
+  const sandbox = uiMeta?.sandbox;
 
-  return { html, csp, permissions };
+  return { html, csp, permissions, sandbox };
 }
 
 
 export function loadSandboxProxy(
   iframe: HTMLIFrameElement,
   csp?: McpUiResourceCsp,
   permissions?: McpUiResourcePermissions,
+  sandbox?: McpUiResourceSandbox,
 ): Promise<boolean> {
   // Prevent reload
   if (iframe.src) return Promise.resolve(false);
 
-  iframe.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms");
+  // Set sandbox attribute on outer iframe. In practice, these will match the inner
+  // iframe sandbox capabilities, but at a minimum they must be a superset of the
+  // inner iframe's sandbox allowances.
+  iframe.setAttribute("sandbox", buildSandboxAttribute(sandbox));
 
   // Set Permission Policy allow attribute based on requested permissions
   const allowAttribute = buildAllowAttribute(permissions);
@@ -214,10 +220,10 @@ export async function initializeApp(
     new PostMessageTransport(iframe.contentWindow!, iframe.contentWindow!),
   );
 
-  // Load inner iframe HTML with CSP and permissions metadata
-  const { html, csp, permissions } = await appResourcePromise;
-  log.info("Sending UI resource HTML to MCP App", csp ? `(CSP: ${JSON.stringify(csp)})` : "", permissions ? `(Permissions: ${JSON.stringify(permissions)})` : "");
-  await appBridge.sendSandboxResourceReady({ html, csp, permissions });
+  // Load inner iframe HTML with CSP, permissions, and sandbox metadata
+  const { html, csp, permissions, sandbox } = await appResourcePromise;
+  log.info("Sending UI resource HTML to MCP App", csp ? `(CSP: ${JSON.stringify(csp)})` : "", permissions ? `(Permissions: ${JSON.stringify(permissions)})` : "", sandbox ? `(Sandbox: ${JSON.stringify(sandbox)})` : "");
+  await appBridge.sendSandboxResourceReady({ html, csp, permissions, sandbox });
 
   // Wait for inner iframe to be ready
   log.info("Waiting for MCP App to initialize...");

examples/basic-host/src/index.tsx

@@ -432,10 +432,10 @@ function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppI
   useEffect(() => {
     const iframe = iframeRef.current!;
 
-    // First get CSP and permissions from resource, then load sandbox
+    // First get CSP, permissions, and sandbox from resource, then load sandbox
     // CSP is set via HTTP headers (tamper-proof), permissions via iframe allow attribute
-    toolCallInfo.appResourcePromise.then(({ csp, permissions }) => {
-      loadSandboxProxy(iframe, csp, permissions).then((firstTime) => {
+    toolCallInfo.appResourcePromise.then(({ csp, permissions, sandbox }) => {
+      loadSandboxProxy(iframe, csp, permissions, sandbox).then((firstTime) => {
         // The `firstTime` check guards against React Strict Mode's double
         // invocation (mount → unmount → remount simulation in development).
         // Outside of Strict Mode, this `useEffect` runs only once per

examples/basic-host/src/sandbox.ts

@@ -1,5 +1,5 @@
 import type { McpUiSandboxProxyReadyNotification, McpUiSandboxResourceReadyNotification } from "@modelcontextprotocol/ext-apps/app-bridge";
-import { buildAllowAttribute } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { buildAllowAttribute, buildSandboxAttribute } from "@modelcontextprotocol/ext-apps/app-bridge";
 
 const ALLOWED_REFERRER_PATTERN = /^http:\/\/(localhost|127\.0\.0\.1)(:|\/|$)/;
 
@@ -41,12 +41,15 @@ try {
 // iframe on a separate origin. It creates an inner iframe for untrusted HTML
 // content. Per the specification, the Host and the Sandbox MUST have different
 // origins.
-const inner = document.createElement("iframe");
-inner.style = "width:100%; height:100%; border:none;";
-inner.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms");
-// Note: allow attribute is set later when receiving sandbox-resource-ready notification
-// based on the permissions requested by the app
-document.body.appendChild(inner);
+//
+// The inner iframe is created lazily when the `sandbox-resource-ready`
+// notification arrives (not at file top) so that its `sandbox` attribute is set
+// to the negotiated value *before* the element is inserted into the DOM.
+// Per the HTML spec, mutating the `sandbox` attribute on an already-attached
+// iframe only takes effect after a navigation; `document.write()` is NOT a
+// navigation, so setting the attribute after attachment would leave the old
+// (or default) flags in effect.
+let inner: HTMLIFrameElement | null = null;
 
 const RESOURCE_READY_NOTIFICATION: McpUiSandboxResourceReadyNotification["method"] =
   "ui/notifications/sandbox-resource-ready";
@@ -85,15 +88,27 @@ window.addEventListener("message", async (event) => {
 
     if (event.data && event.data.method === RESOURCE_READY_NOTIFICATION) {
       const { html, sandbox, permissions } = event.data.params;
-      if (typeof sandbox === "string") {
-        inner.setAttribute("sandbox", sandbox);
-      }
+      // sandbox can be a string (raw override) or object (structured flags)
+      const sandboxAttr = typeof sandbox === "string"
+        ? sandbox
+        : buildSandboxAttribute(sandbox);
+      console.log("[Sandbox] Setting sandbox attribute:", sandboxAttr);
+
+      // Create the inner iframe with the final sandbox attribute before
+      // inserting into the DOM, so negotiated flags are enforced immediately.
+      inner = document.createElement("iframe");
+      inner.style.cssText = "width:100%; height:100%; border:none;";
+      inner.setAttribute("sandbox", sandboxAttr);
+
       // Set Permission Policy allow attribute if permissions are requested
       const allowAttribute = buildAllowAttribute(permissions);
       if (allowAttribute) {
         console.log("[Sandbox] Setting allow attribute:", allowAttribute);
         inner.setAttribute("allow", allowAttribute);
       }
+
+      document.body.appendChild(inner);
+
       if (typeof html === "string") {
         // Use document.write instead of srcdoc (which the CesiumJS Map won't work with)
         const doc = inner.contentDocument || inner.contentWindow?.document;
@@ -112,7 +127,7 @@ window.addEventListener("message", async (event) => {
         inner.contentWindow.postMessage(event.data, "*");
       }
     }
-  } else if (event.source === inner.contentWindow) {
+  } else if (inner && event.source === inner.contentWindow) {
     if (event.origin !== OWN_ORIGIN) {
       console.error(
         "[Sandbox] Rejecting message from inner iframe with unexpected origin:",

specification/draft/apps.mdx

@@ -194,6 +194,40 @@ interface UIResourceMeta {
      */
     clipboardWrite?: {},
   },
+  /**
+   * Sandbox flags requested by the UI
+   *
+   * Servers declare which sandbox capabilities their UI needs beyond baseline (allow-scripts, allow-same-origin).
+   * Hosts MAY honor these by adding flags to the iframe sandbox attribute.
+   * Apps SHOULD NOT assume flags are granted; use feature detection as fallback.
+   *
+   */
+  sandbox?: {
+    /**
+     * Allow form submission
+     *
+     * Maps to sandbox `allow-forms` flag
+     */
+    forms?: {},
+    /**
+     * Allow window.open popups
+     *
+     * Maps to sandbox `allow-popups` flag
+     */
+    popups?: {},
+    /**
+     * Allow alert/confirm/prompt/print dialogs
+     *
+     * Maps to sandbox `allow-modals` flag
+     */
+    modals?: {},
+    /**
+     * Allow file downloads
+     *
+     * Maps to sandbox `allow-downloads` flag
+     */
+    downloads?: {},
+  },
   /**
    * Dedicated origin for view
    *
@@ -500,6 +534,7 @@ If the Host is a web page, it MUST wrap the View and communicate with it through
    - Block dangerous features (`object-src 'none'`)
    - Apply restrictive defaults if no CSP metadata is provided
    - If `permissions` is declared, the Sandbox MAY set the inner iframe's `allow` attribute accordingly
+   - If `sandbox` is declared (as object or string), the Sandbox MAY set the inner iframe's `sandbox` attribute accordingly (baseline: `allow-scripts allow-same-origin`)
 6. The Sandbox MUST forward messages sent by the Host to the View, and vice versa, for any method that doesn't start with `ui/notifications/sandbox-`. This includes lifecycle messages, e.g., `ui/initialize` request & `ui/notifications/initialized` notification both sent by the View. The Host MUST NOT send any request or notification to the View before it receives an `initialized` notification.
 7. The Sandbox SHOULD NOT create/send any requests to the Host or to the View (this would require synthesizing new request ids).
 8. The Host MAY forward any message from the View (coming via the Sandbox) to the MCP Apps server, for any method that doesn't start with `ui/`. While the Host SHOULD ensure the View's MCP connection is spec-compliant, it MAY decide to block some messages or subject them to further user approval.
@@ -682,6 +717,13 @@ interface HostCapabilities {
       /** Approved base URIs for the document (base-uri directive). */
       baseUriDomains?: string[];
     };
+    /** Sandbox flags granted by the host. */
+    flags?: {
+      forms?: {};
+      popups?: {};
+      modals?: {};
+      downloads?: {};
+    };
   };
 }
 ```
@@ -1349,7 +1391,13 @@ These messages are reserved for web-based hosts that implement the recommended d
       microphone?: {},
       geolocation?: {},
       clipboardWrite?: {},
-    }
+    },
+    sandbox?: {          // Sandbox flags from resource metadata (or raw string override)
+      forms?: {},        // Allow form submission (allow-forms)
+      popups?: {},       // Allow window.open popups (allow-popups)
+      modals?: {},       // Allow alert/confirm/prompt/print (allow-modals)
+      downloads?: {},    // Allow file downloads (allow-downloads)
+    } | string           // Raw sandbox attribute override
   }
 }
 ```

src/app-bridge.test.ts

@@ -17,6 +17,7 @@ import { App } from "./app";
 import {
   AppBridge,
   getToolUiResourceUri,
+  buildSandboxAttribute,
   isToolVisibilityModelOnly,
   isToolVisibilityAppOnly,
   type McpUiHostCapabilities,
@@ -1048,6 +1049,92 @@ describe("getToolUiResourceUri", () => {
   });
 });
 
+describe("buildSandboxAttribute", () => {
+  const BASELINE = "allow-scripts allow-same-origin";
+
+  describe("baseline handling", () => {
+    it("returns baseline for undefined", () => {
+      expect(buildSandboxAttribute(undefined)).toBe(BASELINE);
+    });
+
+    it("returns baseline for empty object", () => {
+      expect(buildSandboxAttribute({})).toBe(BASELINE);
+    });
+  });
+
+  describe("single flags", () => {
+    it("adds forms flag", () => {
+      expect(buildSandboxAttribute({ forms: {} })).toBe(
+        `${BASELINE} allow-forms`,
+      );
+    });
+
+    it("adds popups flag", () => {
+      expect(buildSandboxAttribute({ popups: {} })).toBe(
+        `${BASELINE} allow-popups`,
+      );
+    });
+
+    it("adds modals flag", () => {
+      expect(buildSandboxAttribute({ modals: {} })).toBe(
+        `${BASELINE} allow-modals`,
+      );
+    });
+
+    it("adds downloads flag", () => {
+      expect(buildSandboxAttribute({ downloads: {} })).toBe(
+        `${BASELINE} allow-downloads`,
+      );
+    });
+  });
+
+  describe("multiple flags", () => {
+    it("adds multiple flags", () => {
+      const result = buildSandboxAttribute({
+        forms: {},
+        popups: {},
+        modals: {},
+        downloads: {},
+      });
+      expect(result).toContain("allow-forms");
+      expect(result).toContain("allow-popups");
+      expect(result).toContain("allow-modals");
+      expect(result).toContain("allow-downloads");
+      expect(result.startsWith(BASELINE)).toBe(true);
+    });
+
+    it("adds forms and popups", () => {
+      const result = buildSandboxAttribute({ forms: {}, popups: {} });
+      expect(result).toContain("allow-forms");
+      expect(result).toContain("allow-popups");
+      expect(result).not.toContain("allow-modals");
+      expect(result).not.toContain("allow-downloads");
+    });
+  });
+
+  describe("undefined values in object", () => {
+    it("ignores undefined values", () => {
+      const result = buildSandboxAttribute({
+        forms: {},
+        popups: undefined,
+        modals: undefined,
+        downloads: undefined,
+      });
+      expect(result).toBe(`${BASELINE} allow-forms`);
+    });
+
+    it("returns baseline when all values are undefined", () => {
+      const result = buildSandboxAttribute({
+        forms: undefined,
+        popups: undefined,
+        modals: undefined,
+        downloads: undefined,
+      });
+      expect(result).toBe(BASELINE);
+    });
+  });
+});
+
 describe("isToolVisibilityModelOnly", () => {
   describe("returns true", () => {
     it("when visibility is exactly ['model']", () => {

src/app-bridge.ts

@@ -81,6 +81,7 @@ import {
   McpUiRequestDisplayModeRequestSchema,
   McpUiRequestDisplayModeResult,
   McpUiResourcePermissions,
+  McpUiResourceSandbox,
   McpUiToolMeta,
 } from "./types";
 export * from "./types";
@@ -188,6 +189,53 @@ export function buildAllowAttribute(
   return allowList.join("; ");
 }
 
+/**
+ * Mapping of McpUiResourceSandbox keys to sandbox attribute values.
+ * @internal
+ */
+const SANDBOX_FLAG_MAP: Record<keyof McpUiResourceSandbox, string> = {
+  forms: "allow-forms",
+  popups: "allow-popups",
+  modals: "allow-modals",
+  downloads: "allow-downloads",
+};
+
+/**
+ * Baseline sandbox flags always included - required for SDK operation.
+ * @internal
+ */
+const BASELINE_SANDBOX = "allow-scripts allow-same-origin";
+
+/**
+ * Build iframe `sandbox` attribute string from sandbox configuration.
+ *
+ * Maps McpUiResourceSandbox to sandbox attribute format, always including
+ * baseline flags (allow-scripts allow-same-origin).
+ *
+ * @param sandbox - Sandbox flags requested by the UI resource
+ * @returns Space-separated sandbox flags including baseline
+ *
+ * @example
+ * ```typescript
+ * const sandbox = buildSandboxAttribute({ forms: {}, popups: {} });
+ * // Returns: "allow-scripts allow-same-origin allow-forms allow-popups"
+ * iframe.setAttribute("sandbox", sandbox);
+ * ```
+ */
+export function buildSandboxAttribute(
+  sandbox: McpUiResourceSandbox | undefined,
+): string {
+  if (!sandbox) return BASELINE_SANDBOX;
+
+  const additional = Object.entries(sandbox)
+    .filter(([_, v]) => v !== undefined)
+    .map(([k]) => SANDBOX_FLAG_MAP[k as keyof McpUiResourceSandbox])
+    .filter(Boolean);
+
+  if (additional.length === 0) return BASELINE_SANDBOX;
+  return [BASELINE_SANDBOX, ...additional].join(" ");
+}
+
 /**
  * Options for configuring {@link AppBridge `AppBridge`} behavior.
  *