@assistant-ui/mcp-docs-server 0.1.31 → 0.1.33

package/.docs/raw/docs/tools/generative-ui.mdx

@@ -0,0 +1,214 @@
+---
+title: Generative UI (JSON spec)
+description: Render agent-described React UI from a JSON spec with a consumer-provided component allowlist.
+---
+
+`MessagePrimitive.GenerativeUI` is a first-class primitive for rendering UI
+described by the agent at runtime as a JSON spec. Instead of hard-coding a
+component per tool, the agent emits a `generative-ui` message part containing
+a tree of components by name. assistant-ui resolves each name against a
+**consumer-provided allowlist** and renders the result.
+
+> The allowlist controls **which** components the agent may render: any name
+> not in it throws a typed `GenerativeUIRenderError` (no implicit fallback). It
+> does not constrain the props passed to those components; see [Security](#security).
+
+> **Opt-in feature:** The default shadcn `Thread` does **not** render
+> `generative-ui` parts. You must wire the primitive explicitly — see
+> [Opt-in wiring](#opt-in-wiring).
+
+## Which generative UI pattern?
+
+assistant-ui uses "generative UI" in three different places. Pick the one that
+matches your integration:
+
+| Pattern | API | Best for | Streaming |
+|---------|-----|----------|-----------|
+| **Generative UI primitive** | `MessagePrimitive.GenerativeUI` + allowlist | Composing dashboards, cards, and layouts from a component vocabulary you ship | Native `generative-ui` parts update progressively when the part spec changes incrementally |
+| **Tool UI** | `Tools({ toolkit })` with `render` | Interactive widgets tied to a known tool (forms, pickers, charts) | Tool **args** stream while the model fills them in |
+| **LangGraph data UI** | `makeAssistantDataUI` + `ui_message` | LangGraph agents emitting UI via the LangGraph stream | UI messages arrive on the LangGraph custom channel |
+
+See also: [Tool UI guide](/docs/tools/tool-ui), [LangGraph generative UI](/docs/runtimes/langgraph/generative-ui).
+
+## When not to use the primitive
+
+- **User input and two-way interaction** → [Tool UI](/docs/tools/tool-ui) or [Interactables](/docs/tools/interactables)
+- **LangGraph `push_ui_message`** → [LangGraph data UI](/docs/runtimes/langgraph/generative-ui)
+- **Untrusted HTML or third-party widgets** → [MCP Apps](/docs/tools/mcp-apps) (sandboxed frames)
+
+## Quick start
+
+### 1. Define your component allowlist
+
+```tsx title="components/gui.tsx"
+const Card = ({ title, children }) => (
+  <div className="rounded-xl border bg-card p-4 shadow-sm">
+    <div className="text-base font-semibold">{title}</div>
+    <div className="mt-2">{children}</div>
+  </div>
+);
+
+const Button = ({ label }) => (
+  <button className="rounded-md bg-primary px-3 py-1.5 text-primary-foreground">
+    {label}
+  </button>
+);
+
+export const componentsAllowlist = { Card, Button };
+```
+
+### 2. Wire the primitive into your message renderer
+
+See [Opt-in wiring](#opt-in-wiring) for all three integration patterns.
+
+### 3. Have the agent emit UI
+
+**ExternalStore / manual messages** attach a native part:
+
+```ts
+{
+  type: "generative-ui",
+  spec: {
+    root: {
+      component: "Card",
+      props: { title: "Welcome" },
+      children: [
+        { component: "Button", props: { label: "Get started" } },
+      ],
+    },
+  },
+}
+```
+
+**AI SDK (`useChatRuntime`)** — the adapter maps tool results to `tool-call`
+parts, not `generative-ui` parts. Use the [AI SDK interim bridge](#pattern-3--ai-sdk-interim-bridge) until a native emission helper ships.
+
+Live examples in [`examples/with-generative-ui`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-generative-ui): Tool UI demo (`/`), static primitive (`/primitive`), GUI chat (`/gui-chat`).
+
+## Opt-in wiring
+
+The stock `@assistant-ui/ui` `Thread` switch returns `null` for unknown part
+types — including `generative-ui`. Add one of these patterns in **your**
+assistant message renderer (~15 lines).
+
+### Pattern 1 — `MessagePrimitive.Parts`
+
+```tsx
+<MessagePrimitive.Parts
+  components={{
+    generativeUI: {
+      components: componentsAllowlist,
+      Fallback: UnknownComponentFallback,
+    },
+  }}
+/>
+```
+
+### Pattern 2 — `GroupedParts` case (shadcn Thread fork)
+
+```tsx
+case "generative-ui":
+  return (
+    <MessagePrimitive.GenerativeUI
+      components={componentsAllowlist}
+      Fallback={UnknownComponentFallback}
+    />
+  );
+```
+
+Also exclude `render_gui` from tool-group chrome in `groupBy` if you use the
+AI SDK bridge (return `null` for that tool name).
+
+### Pattern 3 — AI SDK interim bridge
+
+When using `useChatRuntime`, map a dedicated tool result to the renderer:
+
+```tsx
+case "tool-call":
+  if (part.toolName === "render_gui") {
+    const spec = parseRenderGuiResult(part.result);
+    if (spec) {
+      return (
+        <MessagePrimitive.GenerativeUI
+          spec={spec}
+          components={componentsAllowlist}
+          Fallback={UnknownComponentFallback}
+        />
+      );
+    }
+  }
+  return part.toolUI ?? <ToolFallback {...part} />;
+```
+
+The message store still holds a `tool-call` on this path — not a
+`generative-ui` part. See `examples/with-generative-ui/app/gui-chat` for a
+working reference.
+
+Bare strings act as inline text leaves.
+
+## Spec shape
+
+```ts
+type GenerativeUINode =
+  | string
+  | {
+      component: string;             // resolved against the allowlist
+      props?: Record<string, unknown>;
+      children?: GenerativeUINode[];
+      key?: string;                   // optional stable React key
+    };
+
+type GenerativeUISpec = {
+  root: GenerativeUINode | GenerativeUINode[];
+};
+```
+
+The spec is plain JSON — easy for any agent to emit, and easy to validate
+on the server before delivery.
+
+## Streaming
+
+When a message contains native `generative-ui` parts whose `spec` updates
+incrementally (for example via ExternalStore), the primitive renders
+progressively as nodes and props arrive.
+
+The AI SDK `render_gui` tool path returns the full spec at **tool completion**
+— not incrementally during the tool execute step. For args streaming during
+generation, use [Tool UI](/docs/tools/tool-ui) instead.
+
+## Security
+
+The allowlist is the boundary on **which** components render: a spec can only instantiate components you put in the registry, with no `eval` and no dynamic import (names are looked up in the registry and nothing else). An unknown name throws `GenerativeUIRenderError` or invokes your `Fallback`.
+
+It does **not** constrain the `props` the agent supplies. Spec props are spread directly onto your allowlisted components, so treat every allowlisted component as receiving untrusted input: never forward agent-supplied props into `dangerouslySetInnerHTML`, validate or reject `href` / `src` values (for example block `javascript:` URLs), and avoid passing spec props anywhere they become executable. The safest allowlisted components accept only primitive, display-oriented props.
+
+## Error handling
+
+Unknown component names throw `GenerativeUIRenderError` with a typed
+`componentName` field. Catch it with a React error boundary, or pass a
+`Fallback` component to opt into a soft-fail UX:
+
+```tsx
+<MessagePrimitive.GenerativeUI
+  components={componentsAllowlist}
+  Fallback={({ component }) => (
+    <span className="rounded bg-muted px-1.5 py-0.5 font-mono text-xs">
+      unknown component: {component}
+    </span>
+  )}
+/>
+```
+
+## Composing with other primitives
+
+`generative-ui` is a regular `MessagePart` type, so it composes cleanly with
+`MessagePrimitive.Parts`, `MessagePrimitive.PartByIndex`, and
+`MessagePrimitive.GroupedParts`. Render it alongside text, tool calls, and
+reasoning in the same message.
+
+## Why a primitive (not just a tool)
+
+Tool-call UI is great when the agent already invoked a known tool. Generative
+UI flips it: the agent _composes_ UI from a vocabulary you ship. Useful for
+dashboards, status panels, and structured layouts — not for collecting user
+input (use Tool UI for that).

package/.docs/raw/docs/tools/index.mdx

@@ -0,0 +1,76 @@
+---
+title: Tools
+description: Give the model callable capabilities with assistant-ui toolkits — define frontend, backend, human, and provider tools, render tool calls as interactive UI, and connect MCP servers.
+platforms: ["react"]
+---
+
+Tools are how the model takes action: fetch data, call an API, query a database, drive your UI, or run a workflow. In assistant-ui you declare tools in a **toolkit** — a named map where each key is the tool name the model sees and each value describes the tool's schema, where it runs, and how its call renders in the chat.
+
+## Start here
+
+<Cards>
+  <Card title="Defining Tools" href="/docs/tools/defining-tools">
+    Author a toolkit with the `"use generative"` directive — frontend, backend, human, and provider tools, with the schema, executor, and renderer in one file.
+  </Card>
+  <Card title="Backend Tools" href="/docs/tools/backend">
+    Wire a toolkit into your AI SDK route with `generativeTools` / `frontendTools`, mix client and server tools, and round-trip multi-modal results.
+  </Card>
+  <Card title="Tool UI" href="/docs/tools/tool-ui">
+    Render tool calls as custom components — loading and result states, human-in-the-loop, approvals, and streaming.
+  </Card>
+  <Card title="Dynamic Tools" href="/docs/tools/dynamic-tools">
+    Tools whose executor closes over React state, via `stubTool()` + `useAuiToolOverrides`.
+  </Card>
+</Cards>
+
+## Two ways to define a toolkit
+
+<Callout type="info">
+  **`"use generative"` + `defineToolkit`** — for tools you author yourself
+  (browser or your own backend). The compiler co-locates the schema, executor,
+  and renderer in one file and splits them across the client/server boundary.
+
+  **Plain `satisfies Toolkit`** — for tools that already execute elsewhere (an
+  MCP server, a separate backend route, a LangGraph node) where you only attach a
+  renderer.
+</Callout>
+
+In a `"use generative"` file every tool declares an `execute` and the kind is
+**inferred** from it (you never write `type`). In a plain toolkit you author
+`type` and write render-only `{ type: "backend", render }` entries. See
+[Defining Tools](/docs/tools/defining-tools#two-ways-to-define-a-toolkit).
+
+## Rendering AI output as UI
+
+assistant-ui has a few ways to turn model output into React UI. Pick by **who decides what renders**:
+
+| You want… | Use | The decider |
+| --- | --- | --- |
+| A custom component for a known tool call (form, picker, chart, status) | [Tool UI](/docs/tools/tool-ui) — `render` on a toolkit entry | the **model**, by calling the tool |
+| Persistent, out-of-thread state the AI can read and write | [Interactables](/docs/tools/interactables) | the **model + the user**, bidirectionally |
+| UI composed from a component vocabulary you ship, described as a JSON spec | [Generative UI (JSON spec)](/docs/tools/generative-ui) — `MessagePrimitive.GenerativeUI` | the **model**, composing a tree |
+| UI pushed by a LangGraph node alongside messages | [LangGraph Generative UI](/docs/runtimes/langgraph/generative-ui) — `makeAssistantDataUI` | the **backend / orchestrator** |
+
+## Connect external tools
+
+<Cards>
+  <Card title="MCP (server-side)" href="/docs/tools/mcp">
+    Wire one or more MCP servers into your API route as a tool catalog.
+  </Card>
+  <Card title="User-managed MCP" href="/docs/tools/user-managed-mcp">
+    Let end users add and authenticate MCP servers from the browser.
+  </Card>
+  <Card title="MCP Apps" href="/docs/tools/mcp-apps">
+    Render MCP UI resources (`ui://`) inline in sandboxed frames.
+  </Card>
+  <Card title="Multi-Agent" href="/docs/tools/multi-agent">
+    Render sub-agent conversations inside a tool call.
+  </Card>
+</Cards>
+
+## Reference & components
+
+- [Tools API Reference](/docs/api-reference/tools) — `tool`, `Toolkit`, `Tools`, and the tool-status hooks.
+- [`ToolFallback`](/docs/ui/tool-fallback) — a default tool card for tools with no custom UI.
+- [`ToolGroup`](/docs/ui/tool-group) — collapse consecutive tool calls into one container.
+- [Migrating Tools to Toolkits](/docs/migrations/toolkit-tools) — move off the deprecated `makeAssistantTool` / `useAssistantToolUI` APIs.

package/.docs/raw/docs/{guides → tools}/interactables.mdx

@@ -1,6 +1,6 @@
 ---
-title: Interactables
-description: Persistent UI whose state can be read and updated by the AI assistant.
+title: Interactable Components
+description: Build persistent UI elements whose state the AI can read and update — copilot interactables in React with assistant-ui for forms, dashboards, and tools.
 platforms: ["react"]
 ---
 
@@ -399,5 +399,5 @@ See the complete [with-interactables example](https://github.com/assistant-ui/as
 
 ## Related
 
-- [Generative UI](/docs/guides/tool-ui) — Inline tool call UIs rendered inside messages
+- [Tool UI](/docs/tools/tool-ui) — Inline tool call UIs rendered inside messages
 - [LangGraph Generative UI](/docs/runtimes/langgraph/generative-ui) — Structured UI components emitted by a LangGraph graph alongside messages

package/.docs/raw/docs/tools/mcp-apps.mdx

@@ -0,0 +1,231 @@
+---
+title: MCP Apps
+description: Render MCP App UI resources inline in chat. Native renderer for the Model Context Protocol Apps spec — sandboxed iframes, JSON-RPC bridge, AI SDK integration.
+platforms: ["react"]
+---
+
+[MCP Apps](https://apps.extensions.modelcontextprotocol.io/) lets a Model Context Protocol server ship a UI resource alongside a tool — a self-contained HTML widget that the chat host renders inline when the tool is called. assistant-ui ships a native renderer that mounts the widget in a sandboxed iframe via [`SafeContentFrame`](/safe-content-frame) and runs a JSON-RPC postMessage bridge so the widget can call tools, send messages, request a display mode, and read host context.
+
+## Overview
+
+When an MCP server attaches a `_meta.ui.resourceUri` (the [`text/html;profile=mcp-app`](https://apps.extensions.modelcontextprotocol.io/api/index.html) MIME) to a tool, AI SDK forwards that metadata through the message stream. assistant-ui's renderer picks it up off the `mcp` field on `ToolCallMessagePart`, fetches the resource through your backend route, and mounts it.
+
+The renderer only acts on URIs that start with `ui://` (per the MCP Apps spec). Tools whose `resourceUri` uses any other scheme are treated as non-MCP-Apps tools and fall through to your regular tool UI.
+
+The widget communicates back through a JSON-RPC bridge:
+
+- **widget → host requests**: `ui/initialize`, `tools/call`, `resources/read`, `resources/list`, `openLink`, `sendMessage`, `requestDisplayMode`, `updateModelContext`
+- **host → widget notifications**: tool input streaming, tool result, host context changes
+- **widget → host notifications**: initialized, size changed, log, error, request teardown
+
+Capability presence is determined at mount time by which handlers you provide. Unknown methods return JSON-RPC `-32601`; bad params return `-32602`.
+
+## Quick start
+
+The renderer talks to a backend route you expose — the MCP client lives server-side so credentials and transport stay out of the browser. The route receives `{ method, params }` POSTs and dispatches to your MCP client.
+
+### Client
+
+Compose `McpAppRenderer({...})` into your `Tools` resource. Provide `host.url` pointing at your route. Any tool-call part carrying `mcp.app` metadata renders the MCP App widget automatically.
+
+```tsx
+import {
+  useAui,
+  Tools,
+  McpAppRenderer,
+  McpAppsRemoteHost,
+} from "@assistant-ui/react";
+
+function MyAssistant() {
+  useAui({
+    tools: Tools({
+      toolkit: myToolkit,
+      mcpApp: McpAppRenderer({
+        host: McpAppsRemoteHost({ url: "/api/mcp-apps" }),
+        hostInfo: { name: "my-app", version: "1.0.0" },
+        hostContext: { theme: "light" },
+      }),
+    }),
+  });
+  // ...
+}
+```
+
+`McpAppsRemoteHost` is the default host strategy — it POSTs `{ method, params }` to your route. A different strategy (e.g. a client-side MCP client) can be plugged in by writing a custom resource that returns the same `McpAppsHost` shape (`{ loadResource, callTool, readResource, listResources }`).
+
+`openLink` is auto-wired to `window.open(url, "_blank", "noopener,noreferrer")`. `sendMessage` is auto-wired to append a user message to the current thread (accepts `string`, `{ prompt }`, `{ text }`, or `{ message }`).
+
+### Route handler
+
+The route accepts `POST` requests with `{ method, params }` JSON bodies. Dispatch by method name and return the result as JSON. Example for Next.js App Router:
+
+```ts
+// app/api/mcp-apps/route.ts
+import { experimental_createMCPClient } from "ai";
+
+let clientPromise: ReturnType<typeof experimental_createMCPClient> | undefined;
+const getClient = () => {
+  clientPromise ??= experimental_createMCPClient({
+    transport: { type: "sse", url: process.env.MCP_SERVER_URL! },
+  });
+  return clientPromise;
+};
+
+export async function POST(req: Request) {
+  const { method, params } = await req.json();
+  const client = await getClient();
+
+  switch (method) {
+    case "mcp-apps/read-resource": {
+      const { contents } = await client.readResource({ uri: params.uri });
+      const c = contents.find((x: { uri: string }) => x.uri === params.uri);
+      return Response.json({
+        uri: params.uri,
+        mimeType: "text/html;profile=mcp-app",
+        html: c?.text ?? "",
+      });
+    }
+    case "tools/call": {
+      const tools = await client.tools();
+      const tool = tools[params.name];
+      if (!tool?.execute) {
+        return Response.json({ error: "Tool not callable" }, { status: 400 });
+      }
+      return Response.json(
+        await tool.execute(params.arguments ?? {}, {
+          toolCallId: `mcp-apps-bridge-${crypto.randomUUID()}`,
+          messages: [],
+        }),
+      );
+    }
+    case "resources/read":
+      return Response.json(await client.readResource({ uri: params.uri }));
+    case "resources/list":
+      return Response.json(await client.listResources(params));
+    default:
+      return Response.json({ error: "Unsupported method" }, { status: 400 });
+  }
+}
+```
+
+The renderer POSTs four method names: `mcp-apps/read-resource`, `tools/call`, `resources/read`, `resources/list`. Reject anything else server-side and apply your own auth / rate limiting in the route.
+
+Per-name `setToolUI` registrations always win over the MCP fallback — you can still customize specific tools.
+
+## AI SDK integration
+
+`@assistant-ui/react-ai-sdk` forwards `callProviderMetadata.mcp.app` from AI SDK tool UI parts into `ToolCallMessagePart.mcp.app`. With AI SDK 5.x and an MCP-Apps-capable MCP server, no extra wiring is required on the part shape.
+
+The rich UI comes from the MCP server's metadata, not from the model, so the path is identical whichever provider drives the conversation. Running Claude is just a different `model:` in `streamText` (`anthropic("claude-sonnet-4-6")` via `@ai-sdk/anthropic`); the MCP server, `splitMcpAppTools`, and the renderer are unchanged. MCP Apps is an open standard in the MCP ecosystem (Claude is one of its hosts), so a standard MCP-Apps server renders out of the box. The bridge below is only needed for servers that use OpenAI's `openai/outputTemplate` convention, again independent of which model you run.
+
+On the chat route, use `splitMcpAppTools()` (from `@ai-sdk/mcp`) to keep app-only tools out of the model's view:
+
+```ts
+import { splitMcpAppTools } from "@ai-sdk/mcp";
+
+const tools = await client.listTools();
+const { modelVisible } = splitMcpAppTools(tools);
+
+const result = streamText({
+  model: openai("gpt-5.4-nano"),
+  tools: modelVisible.tools,
+  // ...
+});
+```
+
+### OpenAI Apps SDK servers
+
+[OpenAI Apps SDK](https://developers.openai.com/apps-sdk) servers carry the same `ui://` template under a different convention: the pointer is `_meta["openai/outputTemplate"]` on the tool definition (not `_meta.ui.resourceUri`), and the resource is served as `text/html+skybridge` rather than `text/html;profile=mcp-app`. `@ai-sdk/mcp` does not recognize `openai/outputTemplate`, so it never populates `callProviderMetadata.mcp.app` and the renderer stays idle.
+
+The renderer needs no change; you only have to surface the pointer. assistant-ui already reads `result._meta["ui/resourceUri"]` off tool results, so the smallest bridge is to copy the template onto the result by tool name. Build the map once from the tool listing, then stamp it inside each tool's `execute`:
+
+```ts
+import type { Tool } from "ai";
+
+// reuse the listTools() result from the AI SDK integration step above; no second round-trip
+const templateByTool = new Map(
+  tools.tools
+    .filter((t) => typeof t._meta?.["openai/outputTemplate"] === "string")
+    .map((t) => [t.name, t._meta["openai/outputTemplate"] as string]),
+);
+
+const withTemplateUri = (tool: Tool, name: string): Tool => {
+  const uri = templateByTool.get(name);
+  const exec = tool.execute;
+  if (!uri || !exec) return tool;
+  return {
+    ...tool,
+    execute: async (args, options) => {
+      const result = (await exec(args, options)) as { _meta?: Record<string, unknown> };
+      return { ...result, _meta: { ...result._meta, "ui/resourceUri": uri } };
+    },
+  } satisfies Tool;
+};
+```
+
+Wrap the AI SDK tool objects before handing them to `streamText`:
+
+```ts
+const aiTools = await client.tools();
+const wrappedTools = Object.fromEntries(
+  Object.entries(aiTools).map(([name, t]) => [name, withTemplateUri(t, name)]),
+);
+// pass wrappedTools to streamText
+```
+
+Your `mcp-apps/read-resource` handler reads the `ui://` resource as in the route example above. Set the response `mimeType` to the `text/html;profile=mcp-app` literal that `McpAppResource` expects and keep the server's HTML in `html`; don't forward the raw `text/html+skybridge` value, which the type rejects.
+
+The cleaner long-term fix is upstream: if `@ai-sdk/mcp`'s `getMCPAppToolMeta` also read `openai/outputTemplate`, then `callProviderMetadata.mcp.app` would populate automatically and this bridge would be unnecessary.
+
+## Bridge protocol
+
+The bridge implements the MCP UI JSON-RPC protocol over `window.postMessage`, filtered by both `event.source === frame.iframe.contentWindow` AND `event.origin === frame.origin` — the cross-origin domain `SafeContentFrame` issues per render. Messages from any other origin or window are dropped silently.
+
+### Widget → host requests
+
+| Method | Notes |
+|---|---|
+| `ui/initialize` | Returns `{ protocolVersion, host, hostContext, capabilities }`. Always supported. |
+| `tools/call` | Routed to `host.url` with method `tools/call`. Optional `handlers.allowedTools` allowlist. Invalid `arguments` shape → `-32602`. |
+| `resources/read` | Routed to `host.url` with method `resources/read`. |
+| `resources/list` | Routed to `host.url` with method `resources/list`. |
+| `openLink` | Requires `handlers.openLink`. Rejects non-`http(s)` URLs with `-32602`. |
+| `sendMessage` | Requires `handlers.sendMessage`. |
+| `requestDisplayMode` | Requires `handlers.requestDisplayMode`. Modes: `inline`, `fullscreen`, `pip`. |
+| `updateModelContext` | Requires `handlers.updateModelContext`. |
+
+When a handler isn't provided, the bridge returns JSON-RPC `-32601` (method not found) — which is also how `capabilities` is reported in the `ui/initialize` response.
+
+### Host → widget notifications
+
+- `notifications/tools/call/input` — sent whenever `part.args` (the streaming tool input) changes
+- `notifications/tools/call/result` — sent when the tool result lands (including error envelopes)
+- `notifications/host_context/changed` — sent when `hostContext` changes (e.g. user toggles theme)
+
+### Widget → host notifications
+
+`notifications/initialized`, `notifications/size_changed`, `notifications/log`, `notifications/error`, `notifications/request_teardown` — wire them via `handlers.onInitialized`, `onSizeChange`, `onLog`, `onError`, `onRequestTeardown` respectively.
+
+If the widget never sends `notifications/initialized` (broken or non-spec-compliant), the host flushes its queued notifications after a 5-second safety timeout so the iframe doesn't appear hung.
+
+## Sandboxing
+
+The iframe is built with [`SafeContentFrame`](/safe-content-frame), which serves each widget from a content-hashed cross-origin so the host page is not reachable by `same-origin` references. Default sandbox flags are `allow-same-origin allow-scripts`. Tune via the `sandbox` field on `McpAppRendererOptions`:
+
+```tsx
+McpAppRenderer({
+  // ...
+  sandbox: {
+    sandbox: ["allow-forms", "allow-popups"],
+    enableBrowserCaching: true,
+    className: "my-mcp-app",
+  },
+});
+```
+
+## Security notes
+
+- Widgets run cross-origin in a sandboxed iframe. The bridge filters incoming messages by both source window and origin.
+- The host route is your auth boundary — apply session checks, rate limiting, and per-tool allowlists there. The renderer trusts whatever the route returns.
+- `openLink` rejects non-`http(s)` URLs at the bridge layer, but your `openLink` handler should still treat the URL as untrusted (e.g. always use `noopener,noreferrer`).
+- Keep `host` and `handlers` references stable across renders (e.g. module-scope constants or `useMemo`); an unstable identity will tear down and refetch the widget on every parent re-render.