feat(client): add CSP query parameter support for HTTP header-based CSP

Add support for passing CSP configuration via URL query parameter (?csp=<json>)
to the sandbox proxy. This enables proxy servers to set Content-Security-Policy
via HTTP headers (tamper-proof) rather than relying on meta tags or postMessage.

Changes:
- AppFrame.tsx: Build sandbox URL with CSP query param before loading iframe
- SandboxConfig.csp: Updated docs explaining query-param + postMessage fallback
- using-a-proxy.md: Added CSP Query Parameter section with server-side example
- Updated architecture diagram to show CSP flow through server

The CSP is still sent via postMessage as a fallback for proxies that don't
support the query parameter approach.

See: modelcontextprotocol/ext-apps#234
Claude-Generated-By: Claude Code (cli/claude-opus-4-5=100%)
Claude-Steers: 2
Claude-Permission-Prompts: 0
Claude-Escapes: 0

Author: ochafik

docs/src/guide/client/using-a-proxy.md

@@ -36,9 +36,12 @@ You can find a complete example for a site with restrictive CSP that uses the ho
 ```mermaid
 sequenceDiagram
   participant Host as Host Page
+  participant Server as Proxy Server
   participant Proxy as Proxy iframe
   participant Inner as Inner iframe (UI widget)
-  Host->>Proxy: Load proxy (with "?url" or "?contentType=rawhtml")
+  Host->>Server: Request proxy (with "?csp=<json>&contentType=rawhtml")
+  Server->>Server: Parse CSP from query param
+  Server-->>Proxy: Serve HTML with CSP HTTP headers
   alt External URL
     Proxy->>Inner: Create with src = decoded url
   else rawHtml
@@ -79,6 +82,56 @@ A valid proxy script must:
 3.  **Sandbox the Iframe**: For external URLs, the nested iframe should be sandboxed with `allow-scripts allow-same-origin`. For raw HTML mode, the inner iframe does **not** use a sandbox attribute—this is intentional because `document.write()` requires same-origin access to the iframe's document. Security for raw HTML is enforced by the outer iframe's sandbox (controlled by the host) and the double-iframe isolation architecture.
 4.  **Forward `postMessage` Events**: To allow communication between the host application and the embedded external URL, the proxy needs to forward `message` events between `window.parent` and the iframe's `contentWindow`. For security, it's critical to use a specific `targetOrigin` instead of `*` in `postMessage` calls whenever possible. The `targetOrigin` for messages to the iframe should be the external URL's origin; Messages to the parent will default to `*`.
 5.  **Permissive Proxy CSP**: Serve the proxy page with a permissive CSP that does not block nested iframe content (e.g., allowing scripts, styles, images) since the host CSP is intentionally not applied on the proxy origin.
+6.  **(Recommended) CSP via HTTP Headers**: For enhanced security, the proxy server can read a `csp` query parameter and set Content-Security-Policy HTTP headers. See [CSP Query Parameter](#csp-query-parameter) below.
+
+### CSP Query Parameter
+
+When CSP metadata is provided, `mcp-ui` appends it to the proxy URL as a `?csp=<json>` query parameter. This allows proxy servers to set CSP via HTTP headers, which is more secure than meta tags or postMessage-based CSP injection (which can be bypassed by malicious content).
+
+**Example URL:**
+```
+https://my-proxy.com/?contentType=rawhtml&csp={"connectDomains":["https://api.example.com"],"resourceDomains":["https://cdn.example.com"]}
+```
+
+**Server-side implementation (Express example):**
+```typescript
+import type { McpUiResourceCsp } from '@modelcontextprotocol/ext-apps/app-bridge';
+
+app.get('/proxy', (req, res) => {
+  let cspConfig: McpUiResourceCsp | undefined;
+  if (typeof req.query.csp === 'string') {
+    try {
+      cspConfig = JSON.parse(req.query.csp);
+    } catch (e) { /* ignore invalid JSON */ }
+  }
+
+  const cspHeader = buildCspHeader(cspConfig);
+  res.setHeader('Content-Security-Policy', cspHeader);
+  res.sendFile('proxy.html');
+});
+
+function buildCspHeader(csp?: McpUiResourceCsp): string {
+  const resourceDomains = csp?.resourceDomains?.join(' ') ?? '';
+  const connectDomains = csp?.connectDomains?.join(' ') ?? '';
+  const frameDomains = csp?.frameDomains?.join(' ');
+
+  return [
+    "default-src 'self' 'unsafe-inline'",
+    `script-src 'self' 'unsafe-inline' 'unsafe-eval' blob: data: ${resourceDomains}`.trim(),
+    `style-src 'self' 'unsafe-inline' blob: data: ${resourceDomains}`.trim(),
+    `img-src 'self' data: blob: ${resourceDomains}`.trim(),
+    `font-src 'self' data: blob: ${resourceDomains}`.trim(),
+    `connect-src 'self' ${connectDomains}`.trim(),
+    `worker-src 'self' blob: ${resourceDomains}`.trim(),
+    frameDomains ? `frame-src ${frameDomains}` : "frame-src 'none'",
+    "object-src 'none'",
+  ].join('; ');
+}
+```
+
+::: tip
+The CSP is also sent via `postMessage` after the sandbox loads as a fallback for proxies that don't support the query parameter approach. However, HTTP header-based CSP is strongly recommended as it's tamper-proof.
+:::
 
 ### Example Self-Hosted Proxy
 

sdks/typescript/client/src/components/AppFrame.tsx

@@ -12,6 +12,23 @@ import {
 
 import { setupSandboxProxyIframe } from '../utils/app-host-utils';
 
+/**
+ * Build sandbox URL with CSP query parameter for HTTP header-based CSP enforcement.
+ *
+ * When the proxy server supports it, CSP passed via query parameter allows the server
+ * to set CSP via HTTP headers (tamper-proof) rather than relying on meta tags or
+ * postMessage-based CSP injection (which can be bypassed by malicious content).
+ *
+ * @see https://github.com/modelcontextprotocol/ext-apps/pull/234
+ */
+function buildSandboxUrl(baseUrl: URL, csp?: McpUiResourceCsp): URL {
+  const url = new URL(baseUrl.href);
+  if (csp && Object.keys(csp).length > 0) {
+    url.searchParams.set('csp', JSON.stringify(csp));
+  }
+  return url;
+}
+
 /**
  * Information about the guest app, available after initialization.
  */
@@ -30,7 +47,19 @@ export interface SandboxConfig {
   url: URL;
   /** Override iframe sandbox attribute (default: "allow-scripts allow-same-origin allow-forms") */
   permissions?: string;
-  /** CSP metadata to forward to the sandbox proxy */
+  /**
+   * CSP metadata for the sandbox.
+   *
+   * This CSP is passed to the sandbox proxy in two ways:
+   * 1. Via URL query parameter (`?csp=<json>`) - allows servers that support it to set
+   *    CSP via HTTP headers (tamper-proof, recommended)
+   * 2. Via postMessage after sandbox loads - fallback for proxies that don't parse query params
+   *
+   * For maximum security, use a proxy server that reads the `csp` query parameter and sets
+   * Content-Security-Policy HTTP headers accordingly.
+   *
+   * @see https://github.com/modelcontextprotocol/ext-apps/pull/234
+   */
   csp?: McpUiResourceCsp;
 }
 
@@ -120,7 +149,11 @@ export const AppFrame = (props: AppFrameProps) => {
 
   // Effect 1: Set up sandbox iframe and connect AppBridge
   useEffect(() => {
-    const sandboxUrlString = sandbox.url.href;
+    // Build sandbox URL with CSP query parameter for HTTP header-based CSP enforcement.
+    // Servers that support this will parse the CSP from the query param and set it via
+    // HTTP headers (tamper-proof). The CSP is also sent via postMessage as fallback.
+    const sandboxUrl = buildSandboxUrl(sandbox.url, sandbox.csp);
+    const sandboxUrlString = sandboxUrl.href;
 
     // If we already have an iframe set up for this sandbox URL AND the same appBridge, skip setup
     // This preserves the iframe state across React re-renders (including StrictMode)
@@ -151,7 +184,7 @@ export const AppFrame = (props: AppFrameProps) => {
           currentAppBridgeRef.current = null;
         }
 
-        const { iframe, onReady } = await setupSandboxProxyIframe(sandbox.url);
+        const { iframe, onReady } = await setupSandboxProxyIframe(sandboxUrl);
 
         if (!mounted) return;
 
@@ -214,7 +247,7 @@ export const AppFrame = (props: AppFrameProps) => {
     return () => {
       mounted = false;
     };
-  }, [sandbox.url, appBridge]);
+  }, [sandbox.url, sandbox.csp, appBridge]);
 
   // Effect 2: Send HTML to sandbox when bridge is connected
   useEffect(() => {