@assistant-ui/mcp-docs-server 0.1.39 → 0.2.1

package/.docs/raw/docs/tools/interactables.mdx

@@ -41,7 +41,7 @@ Interactables allow both agents and users to read and edit tool UIs and componen
 
 ```tsx
 import {
-  useAui,
+  AuiConfig,
   unstable_Interactables,
   AssistantRuntimeProvider,
   Tools,
@@ -50,13 +50,15 @@ import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 
 function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
   const runtime = useChatRuntime();
-
-  const aui = useAui({
+  const config = AuiConfig({
     unstable_interactables: unstable_Interactables(), // [!code ++]
   });
 
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    <AssistantRuntimeProvider
+      runtime={runtime}
+      config={config}
+    >
       {children}
     </AssistantRuntimeProvider>
   );
@@ -66,7 +68,7 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 <Callout type="idea">
   The legacy `interactables: Interactables()` scope and the new
   `unstable_interactables: unstable_Interactables()` scope are mutually
-  exclusive. Mount only one interactables API in a single `useAui` provider.
+  exclusive. Mount only one interactables API in a single provider config.
 </Callout>
 
 This scope is needed for both kinds of interactable. Thread-scoped interactables also live in a toolkit, which you register with `Tools` (shown below).
@@ -166,7 +168,7 @@ const toolkit = defineToolkit({
 Register the toolkit alongside the `unstable_Interactables` scope:
 
 ```tsx
-const aui = useAui({
+AuiConfig({
   unstable_interactables: unstable_Interactables(),
   tools: Tools({ toolkit }), // [!code ++]
 });
@@ -199,7 +201,7 @@ export async function POST(req: Request) {
   const { messages } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(injectInteractableContext(messages)), // [!code ++]
   });
 
@@ -592,7 +594,12 @@ An app-scoped item's history covers the current conversation, not its full cross
 By default, app-scoped interactable state is in-memory and lost on page refresh. You can add persistence by passing an adapter to `unstable_Interactables`:
 
 ```tsx
-import { useAui, unstable_Interactables } from "@assistant-ui/react";
+import {
+  AuiConfig,
+  AuiProvider,
+  useAui,
+  unstable_Interactables,
+} from "@assistant-ui/react";
 
 // Module-level (or memoized) so the adapter identity is stable across renders.
 const persistenceAdapter = {
@@ -606,19 +613,23 @@ const persistenceAdapter = {
 };
 
 function MyRuntimeProvider({ children }) {
-  const aui = useAui({
+  const aui = useAui();
+  const config = AuiConfig({
     unstable_interactables: unstable_Interactables({
       persistence: persistenceAdapter,
     }),
   });
-
-  return /* ... */;
+  return (
+    <AuiProvider extends={aui} config={config}>
+      {children}
+    </AuiProvider>
+  );
 }
 ```
 
 `load` is called when the adapter is attached and may be async. Loaded state seeds interactables as they register; a local edit made while a slow `load` is still in flight wins over the loaded value. Thread-scoped interactables are not touched by the adapter; they persist via thread history.
 
-For dynamic setups (an adapter that depends on auth), call `aui.interactables().setPersistenceAdapter(adapter)` imperatively instead.
+For dynamic setups (an adapter that depends on auth), call `aui.interactables.setPersistenceAdapter(adapter)` imperatively instead.
 
 ### Sync Status
 
@@ -640,10 +651,10 @@ State changes are automatically debounced (500ms) before saving. When the owning
 For custom persistence strategies, use `exportState` and `importState` directly:
 
 ```tsx
-const snapshot = aui.interactables().exportState();
+const snapshot = aui.interactables.exportState();
 // => { "note-1": { name: "note", state: { title: "Hello" } }, ... }
 
-aui.interactables().importState(snapshot);
+aui.interactables.importState(snapshot);
 // Imported state is picked up when components next register
 ```
 
@@ -1040,10 +1051,10 @@ Every version of an interactable recorded in the current thread, oldest first. E
 
 ### `unstable_Interactables`
 
-The scope resource that manages all interactables. Register it via `useAui`, optionally with a [persistence adapter](#persistence):
+The scope resource that manages all interactables. Register it via your provider's `config`, optionally with a [persistence adapter](#persistence):
 
 ```tsx
-const aui = useAui({
+AuiConfig({
   unstable_interactables: unstable_Interactables({ persistence: myAdapter }),
 });
 ```

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

@@ -36,14 +36,17 @@ Compose `McpAppRenderer({...})` into your `Tools` resource. Provide `host.url` p
 
 ```tsx
 import {
-  useAui,
+  AuiConfig,
+  AuiProvider,
   Tools,
   McpAppRenderer,
   McpAppsRemoteHost,
+  useAui,
 } from "@assistant-ui/react";
 
-function MyAssistant() {
-  useAui({
+function MyAssistant({ children }) {
+  const aui = useAui();
+  const config = AuiConfig({
     tools: Tools({
       toolkit: myToolkit,
       mcpApp: McpAppRenderer({
@@ -53,12 +56,38 @@ function MyAssistant() {
       }),
     }),
   });
-  // ...
+  return (
+    <AuiProvider extends={aui} config={config}>
+      {children}
+    </AuiProvider>
+  );
 }
 ```
 
 `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 }`).
 
+Changes to `headers` or a custom `fetch` function apply to subsequent host requests without reloading the widget. When the account or workspace identity changes, key the host resource explicitly so its UI resource reloads.
+
+Install the resource helper:
+
+```bash
+pnpm add @assistant-ui/tap
+```
+
+```tsx
+import { withKey } from "@assistant-ui/tap";
+
+const mcpApp = McpAppRenderer({
+  host: withKey(
+    workspaceId,
+    McpAppsRemoteHost({
+      url: "/api/mcp-apps",
+      headers: () => getWorkspaceHeaders(workspaceId),
+    }),
+  ),
+});
+```
+
 `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
@@ -154,7 +183,7 @@ const tools = await client.listTools();
 const { modelVisible } = splitMcpAppTools(tools);
 
 const result = streamText({
-  model: openai("gpt-5.4-nano"),
+  model: openai("gpt-5.6-luna"),
   tools: modelVisible.tools,
   // ...
 });
@@ -164,7 +193,7 @@ const result = streamText({
 
 [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`:
+The renderer needs no change; you only have to surface the pointer. assistant-ui reads the canonical `result._meta.ui.resourceUri` off tool results (and still accepts the deprecated flat `result._meta["ui/resourceUri"]`), 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";
@@ -184,7 +213,13 @@ const withTemplateUri = (tool: Tool, name: string): Tool => {
     ...tool,
     execute: async (args, options) => {
       const result = (await exec(args, options)) as { _meta?: Record<string, unknown> };
-      return { ...result, _meta: { ...result._meta, "ui/resourceUri": uri } };
+      return {
+        ...result,
+        _meta: {
+          ...result._meta,
+          ui: { ...(result._meta?.["ui"] as Record<string, unknown>), resourceUri: uri },
+        },
+      };
     },
   } satisfies Tool;
 };
@@ -204,6 +239,59 @@ Your `mcp-apps/read-resource` handler reads the `ui://` resource as in the route
 
 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.
 
+## AG-UI integration
+
+With `@assistant-ui/react-ag-ui`, the backend associates an MCP App with a tool call through an `ACTIVITY_SNAPSHOT`. Include the tool call ID, the app's `ui://` resource URI, and the MCP server identity when routing across multiple servers:
+
+```json
+{
+  "type": "ACTIVITY_SNAPSHOT",
+  "activityType": "mcp-apps",
+  "content": {
+    "toolCallId": "call-1",
+    "resourceUri": "ui://maps/result.html",
+    "serverId": "maps",
+    "result": {
+      "content": [{ "type": "text", "text": "Map ready" }],
+      "structuredContent": { "center": [37.77, -122.42] },
+      "_meta": { "initialView": "street" },
+      "isError": false
+    }
+  }
+}
+```
+
+`serverId` is optional. If it is absent, the runtime accepts `serverHash` as a fallback. Older middleware may omit `toolCallId`, in which case the snapshot applies to the last resolved tool call; new integrations should include it so concurrent tool calls are correlated unambiguously. Emit the snapshot after the tool call's `TOOL_CALL_START`. A snapshot that names a tool call restored from prior history applies to that message directly, so re-emitting the activity after a `MESSAGES_SNAPSHOT` rehydrates its widget; a snapshot for a tool call ID the runtime has never seen is silently ignored.
+
+Send the normal `TOOL_CALL_RESULT` with a concise, model-visible summary:
+
+```json
+{
+  "type": "TOOL_CALL_RESULT",
+  "toolCallId": "call-1",
+  "content": "Map ready"
+}
+```
+
+The snapshot's `result` becomes the widget-visible `part.result`, while the `TOOL_CALL_RESULT.content` string is retained for the model as `part.modelContent`, a text content-part array (`[{ "type": "text", "text": "Map ready" }]`).
+
+Alternatively, AG-UI servers can place MCP host fields directly on `TOOL_CALL_RESULT`:
+
+```json
+{
+  "type": "TOOL_CALL_RESULT",
+  "toolCallId": "call-1",
+  "content": "Map ready",
+  "structuredContent": { "center": [37.77, -122.42] },
+  "_meta": { "initialView": "street" },
+  "isError": false
+}
+```
+
+In this form, the runtime assembles a `CallToolResult`-shaped `part.result` from `content`, `structuredContent`, `_meta`, and `isError`. At least one of `structuredContent` or `_meta` must be present; when both are absent the enriched path does not activate and the result falls back to the plain `content` string. The `_meta` can also carry the app pointer itself (canonical `ui.resourceUri`, or the deprecated flat `"ui/resourceUri"`), in which case no `ACTIVITY_SNAPSHOT` is needed to activate the widget. A snapshot remains the only carrier for server identity (`serverId`), and when both provide a `resourceUri` the snapshot wins.
+
+The visibility split follows the MCP Apps contract: `content` is model-visible; `structuredContent` and `_meta` are available only to the host and widget. When assistant-ui serializes history into a later AG-UI request, it sends the saved model-visible text and never includes `structuredContent` or `_meta`.
+
 ## 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.
@@ -255,4 +343,4 @@ McpAppRenderer({
 - 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.
+- Keep custom `host` and `handlers` references stable across renders (e.g. module-scope constants or `useMemo`); an unstable custom-host identity keeps the widget in `loadingFallback` while refetching on every parent re-render.

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

@@ -177,7 +177,7 @@ export async function POST(req: Request) {
   const aiToolkit = new AISDKToolkit({ toolkit });
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
     tools: await aiToolkit.tools({ frontend: tools }),
     onFinish: async () => {
@@ -220,7 +220,7 @@ export async function POST(req: Request) {
   const tools = await mcpClient.tools();
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
     tools,
     onFinish: async () => {
@@ -369,7 +369,7 @@ Register the toolkit once with `Tools({ toolkit })`. Renderer keys such as
 ```tsx title="app/components/RuntimeProvider.tsx"
 "use client";
 
-import { AssistantRuntimeProvider, Tools, useAui } from "@assistant-ui/react";
+import { AssistantRuntimeProvider, AuiConfig, Tools } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import type { ReactNode } from "react";
 
@@ -377,10 +377,12 @@ import { toolkit } from "./GitHubIssueToolUI";
 
 export function MyRuntimeProvider({ children }: { children: ReactNode }) {
   const runtime = useChatRuntime();
-  const aui = useAui({ tools: Tools({ toolkit }) });
-
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    <AssistantRuntimeProvider
+      runtime={runtime}
+      config={config}
+    >
       {children}
     </AssistantRuntimeProvider>
   );
@@ -400,7 +402,7 @@ MCP tools execute on the server, so approval is a server-side tool gate, not a `
 const tools = await mcpClient.tools();
 
 const result = streamText({
-  model: openai("gpt-5.4-mini"),
+  model: openai("gpt-5.6-luna"),
   messages: await convertToModelMessages(messages),
   tools,
   toolApproval: {

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

@@ -69,15 +69,15 @@ export default defineToolkit({
 ```
 
 ```tsx title="app/MyRuntimeProvider.tsx"
-import { AssistantRuntimeProvider, Tools, useAui } from "@assistant-ui/react";
+import { AssistantRuntimeProvider, AuiConfig, Tools } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import toolkit from "./toolkit";
 
 function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
   const runtime = useChatRuntime();
-  const aui = useAui({ tools: Tools({ toolkit }) });
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    <AssistantRuntimeProvider runtime={runtime} config={config}>
       {children}
     </AssistantRuntimeProvider>
   );
@@ -190,10 +190,9 @@ const toolkit = defineToolkit({
 });
 
 function App({ runtime }: { runtime: AssistantRuntime }) {
-  const aui = useAui({ tools: Tools({ toolkit }) });
-
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    <AssistantRuntimeProvider runtime={runtime} config={config}>
       <Thread />
     </AssistantRuntimeProvider>
   );
@@ -215,7 +214,7 @@ export async function POST(req: Request) {
   const { messages } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-nano"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
     tools: {
       getWeather: tool({
@@ -331,19 +330,21 @@ export function useAnalyzeDataToolkit(theme: "light" | "dark") {
 ```
 
 ```tsx title="DynamicToolUI.tsx"
-import { AuiProvider, Tools, useAui } from "@assistant-ui/react";
+import { AuiConfig, AuiProvider, Tools, useAui } from "@assistant-ui/react";
 import { useState } from "react";
 import { useAnalyzeDataToolkit } from "./analyze-data-toolkit";
 
 function DynamicToolUI({ children }: { children: React.ReactNode }) {
   const [theme] = useState<"light" | "dark">("light");
   const toolkit = useAnalyzeDataToolkit(theme);
+  const aui = useAui();
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
 
-  const aui = useAui({
-    tools: Tools({ toolkit }),
-  });
-
-  return <AuiProvider value={aui}>{children}</AuiProvider>;
+  return (
+    <AuiProvider extends={aui} config={config}>
+      {children}
+    </AuiProvider>
+  );
 }
 ```
 
@@ -390,18 +391,16 @@ export function useInventoryToolkit(productId: string, productName: string) {
 ```
 
 ```tsx title="ProductPage.tsx"
-import { AuiProvider, Tools, useAui } from "@assistant-ui/react";
+import { AuiConfig, AuiProvider, Tools, useAui } from "@assistant-ui/react";
 import { useInventoryToolkit } from "./inventory-toolkit";
 
 function ProductPage({ productId, productName }) {
   const toolkit = useInventoryToolkit(productId, productName);
-
-  const aui = useAui({
-    tools: Tools({ toolkit }),
-  });
+  const aui = useAui();
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
 
   return (
-    <AuiProvider value={aui}>
+    <AuiProvider extends={aui} config={config}>
       <div>Product details...</div>
     </AuiProvider>
   );
@@ -942,15 +941,20 @@ export function useHeavyComputationToolkit() {
 ```
 
 ```tsx title="HeavyComputationToolProvider.tsx"
-import { AuiProvider, Tools, useAui } from "@assistant-ui/react";
+import { AuiConfig, AuiProvider, Tools, useAui } from "@assistant-ui/react";
 import type { ReactNode } from "react";
 import { useHeavyComputationToolkit } from "./heavy-computation-toolkit";
 
 function HeavyComputationToolProvider({ children }: { children: ReactNode }) {
   const toolkit = useHeavyComputationToolkit();
-  const aui = useAui({ tools: Tools({ toolkit }) });
+  const aui = useAui();
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
 
-  return <AuiProvider value={aui}>{children}</AuiProvider>;
+  return (
+    <AuiProvider extends={aui} config={config}>
+      {children}
+    </AuiProvider>
+  );
 }
 ```
 

package/.docs/raw/docs/tools/user-managed-mcp.mdx

@@ -15,14 +15,14 @@ Both flow through one connection lifecycle, one persisted state surface, and one
 ## How it works
 
 ```
-useAui({ mcp: McpManagerResource({ connectors }) })
+AuiConfig({ mcp: McpManagerResource({ connectors }) })
         │
         ├─ Resource — connection lifecycle, server lookup, OAuth/bearer auth
         ├─ Auto-mounts the modelContext scope when no chat runtime provides one
         └─ Registers connected tools as frontend tools — your chat sees them automatically
 ```
 
-The manager is a single resource. Mount it with `useAui` like any other scope. OAuth (PKCE + RFC 7591 dynamic client registration), bearer, and "no auth" are first-class. Token refresh runs inside the MCP SDK on 401; this package mediates persistence and the redirect step.
+The manager is a single resource. Mount it with `AuiProvider` like any other scope. OAuth (PKCE + RFC 7591 dynamic client registration), bearer, and "no auth" are first-class. Token refresh runs inside the MCP SDK on 401; this package mediates persistence and the redirect step.
 
 ## Setup
 
@@ -38,12 +38,12 @@ The manager is a single resource. Mount it with `useAui` like any other scope. O
 
 ### Mount the manager
 
-Declare your connectors and provide the `mcp` scope on `useAui`. No provider wrapper, no imperative hooks:
+Declare your connectors and provide the `mcp` scope via `AuiProvider`. No imperative hooks:
 
 ```tsx title="app/providers.tsx"
 "use client";
 
-import { AuiProvider, useAui } from "@assistant-ui/react";
+import { AuiConfig, AuiProvider, useAui } from "@assistant-ui/react";
 import { McpManagerResource, defineConnector } from "@assistant-ui/react-mcp";
 
 const connectors = [
@@ -64,13 +64,18 @@ const connectors = [
 ];
 
 export function Providers({ children }: { children: React.ReactNode }) {
-  const aui = useAui({
+  const aui = useAui();
+  const config = AuiConfig({
     mcp: McpManagerResource({
       connectors,
       connectionTimeout: 15_000,
     }),
   });
-  return <AuiProvider value={aui}>{children}</AuiProvider>;
+  return (
+    <AuiProvider extends={aui} config={config}>
+      {children}
+    </AuiProvider>
+  );
 }
 ```
 
@@ -114,7 +119,7 @@ Pass children to override the trigger:
 </McpConfigDialog>
 ```
 
-**Compose your own from primitives** — three namespaces, all unstyled and `data-*`-driven. The iteration primitives take a **render function** so the body re-runs per server with the right scope:
+**Compose your own from primitives.** Four namespaces are available, all unstyled and `data-*`-driven. The iteration primitives take a **render function** so the body re-runs per server with the right scope:
 
 ```tsx title="app/mcp/page.tsx"
 "use client";
@@ -179,7 +184,7 @@ The iteration primitives wrap each item in an `McpServerByIdProvider`, so the ne
 </McpAddFormPrimitive.Root>
 ```
 
-The form owns its own draft state and submits via `aui.mcp().addCustomServer(...)`. Pass a render function to `AuthFields` to fully customize it.
+The form owns its own draft state and submits via `aui.mcp.addCustomServer(...)`. Pass a render function to `AuthFields` to fully customize it.
 
 </Step>
 <Step>
@@ -236,12 +241,56 @@ If no chat runtime is mounted, `McpManagerResource` brings its own minimal `mode
 ```ts
 // In an event handler, never in render.
 const aui = useAui();
-const out = await aui.mcp().server({ id: "linear" }).callTool("search", { q });
+const out = await aui.mcp.server({ id: "linear" }).callTool("search", { q });
 ```
 
 </Step>
 </Steps>
 
+## Form elicitation
+
+Connected servers can request structured user input through form-mode elicitation. Render `McpElicitationPrimitive.Items` inside a server-scoped subtree, then compose fields and response actions from the unstyled primitives:
+
+Answering a request requires composing `McpElicitationPrimitive`, because the server waits for the form response otherwise. Set `elicitation: false` on a connector or custom server to opt it out of advertising the capability. Numeric fields can stay text inputs (parseable strings are coerced); boolean fields must compose a checkbox, because string drafts for booleans are flagged invalid rather than coerced. Clearing a field returns it to the unanswered state, so an empty text input is omitted from the response rather than submitted as `""` or flagged invalid, unless the schema admits `""` for that property through an `enum` member or a `""` default. Render `enum` properties as a select; when `""` is not a member, its blank option is the unanswered state.
+
+```tsx
+import { McpElicitationPrimitive } from "@assistant-ui/react-mcp";
+
+<McpElicitationPrimitive.Items>
+  {() => (
+    <McpElicitationPrimitive.Root>
+      <McpElicitationPrimitive.Message />
+      <McpElicitationPrimitive.Error />
+      <McpElicitationPrimitive.Fields>
+        {({ name, schema, value, setValue }) =>
+          (schema as { type?: string } | undefined)?.type === "boolean" ? (
+            <label>
+              {name}
+              <input
+                type="checkbox"
+                checked={value === true}
+                onChange={(event) => setValue(event.target.checked)}
+              />
+            </label>
+          ) : (
+            <input
+              name={name}
+              value={typeof value === "string" ? value : ""}
+              onChange={(event) => setValue(event.target.value)}
+            />
+          )
+        }
+      </McpElicitationPrimitive.Fields>
+      <McpElicitationPrimitive.Accept>Submit</McpElicitationPrimitive.Accept>
+      <McpElicitationPrimitive.Decline>Decline</McpElicitationPrimitive.Decline>
+      <McpElicitationPrimitive.Cancel>Cancel</McpElicitationPrimitive.Cancel>
+    </McpElicitationPrimitive.Root>
+  )}
+</McpElicitationPrimitive.Items>
+```
+
+Client-side validation errors keep the elicitation pending so the user can correct the form, and `McpElicitationPrimitive.Error` renders the resulting message.
+
 ## Storage
 
 All persisted state — custom server records, OAuth tokens, PKCE verifiers, DCR client info — goes through a single `MCPStorage` resource. Three built-ins:
@@ -253,7 +302,7 @@ All persisted state — custom server records, OAuth tokens, PKCE verifiers, DCR
 ```tsx
 import { McpManagerResource, McpCustomStorage } from "@assistant-ui/react-mcp";
 
-const aui = useAui({
+AuiConfig({
   mcp: McpManagerResource({
     connectors,
     storage: McpCustomStorage({
@@ -312,9 +361,9 @@ Imperative methods: `useAui` + resolve in a callback (never during render):
 const aui = useAui();
 
 // inside an event handler:
-await aui.mcp().addCustomServer({ name, url, auth: { type: "bearer", token } });
-await aui.mcp().server({ id }).connect();
-await aui.mcp().server({ id }).callTool("echo", { text: "hi" });
+await aui.mcp.addCustomServer({ name, url, auth: { type: "bearer", token } });
+await aui.mcp.server({ id }).connect();
+await aui.mcp.server({ id }).callTool("echo", { text: "hi" });
 
 // Build a paginated resource browser/preview UI.
 type ResourcePage = {
@@ -322,7 +371,7 @@ type ResourcePage = {
   nextCursor?: string;
 };
 
-const server = aui.mcp().server({ id });
+const server = aui.mcp.server({ id });
 const resources: ResourcePage["resources"] = [];
 let nextCursor: string | undefined;
 
@@ -346,6 +395,7 @@ What ships:
 
 - Tool listing and invocation, auto-registered as frontend tools
 - Resource listing and reads for app-built browsers or preview panes
+- Form-mode elicitation with app-composed fields and response actions
 - OAuth (PKCE + DCR), bearer, none
 - StreamableHTTP transport
 - Manual connect/disconnect

package/.docs/raw/docs/ui/file.mdx

@@ -115,7 +115,7 @@ import {
 | `File.Icon` | MIME type-aware icon, or pass custom `children` |
 | `File.Name` | Truncated filename |
 | `File.Size` | Human-readable file size |
-| `File.Download` | Download link button |
+| `File.Download` | Download link button; renders nothing without a browser-resolvable target (`sourceType: "id"`, urls that are not http(s)/blob/data) |
 
 ### Custom Icon
 
@@ -134,6 +134,7 @@ The component also exports utility functions:
 ```tsx
 import {
   getMimeTypeIcon,
+  getFileDataKind,
   getBase64Size,
   formatFileSize,
 } from "@/components/assistant-ui/file";
@@ -141,6 +142,10 @@ import {
 // Get icon component for a MIME type
 const Icon = getMimeTypeIcon("application/pdf"); // FileTextIcon
 
+// Classify the data field of a file part; a declared sourceType wins over sniffing, except a data: payload declared as "url"
+const kind = getFileDataKind("https://example.com/report.pdf"); // "url"
+const ref = getFileDataKind("file-abc123", "id"); // "id"
+
 // Calculate size from base64 string
 const bytes = getBase64Size("SGVsbG8gV29ybGQh"); // 12
 

package/.docs/raw/docs/ui/follow-up-suggestions.mdx

@@ -74,6 +74,8 @@ const ThreadViewportFooter = () => {
 
 The component only renders when the thread is not empty, not currently running, and has at least one suggestion. Each suggestion uses `ThreadPrimitive.Suggestion`, replaces the composer text with the prompt, and sends it immediately.
 
+Suggestions stay on a single line. When they overflow, the row scrolls horizontally without a scrollbar, and each edge with clipped content fades out — so no fade shows at the start edge until you scroll.
+
 ## Related Components
 
 - [Thread](/docs/ui/thread) - Complete chat interface with message list and composer