@assistant-ui/mcp-docs-server 0.1.38 → 0.2.0

package/.docs/raw/docs/tools/defining-tools.mdx

@@ -125,7 +125,7 @@ import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import toolkit from "./toolkit";
 
 export function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
-  const runtime = useChatRuntime({ api: "/api/chat" });
+  const runtime = useChatRuntime();
   const aui = useAui({ tools: Tools({ toolkit }) });
 
   return (
@@ -136,6 +136,8 @@ export function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 }
 ```
 
+`useChatRuntime()` targets `/api/chat` by default. To point at a different endpoint or customize requests, see [Custom transport](/docs/runtimes/ai-sdk/v7#custom-transport).
+
 </Step>
 <Step>
 
@@ -461,6 +463,10 @@ export default defineToolkit({
 });
 ```
 
+When two MCP servers expose the same tool name, use `{ server, prefix }` on an
+entry so the model sees distinct names such as `docs_search` and
+`github_search`.
+
 See [MCP](/docs/tools/mcp) for the full server-side and user-managed MCP flows.
 
 ## Advanced

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

@@ -173,6 +173,8 @@ action registry to let interactive nodes call back into your app. This path uses
 the flat `{ "$type": ... }` node shape; the model puts an `$action` object on
 the node, and its `type` is matched against your registered handlers.
 
+Browse the [gallery](/gallery) to see every default vocabulary component rendered live, next to its IR JSON, generated React code, and a usage snippet.
+
 ```tsx
 import {
   JSONGenerativeUI,
@@ -200,8 +202,7 @@ const generative = new JSONGenerativeUI({
 }
 ```
 
-`Select`, `Input`, and `DatePicker` add the user's value as `$input` when they
-fire the action. Unknown action types are ignored and warn in development.
+`Select`, `Input`, `DatePicker`, `Checkbox`, and `RadioGroup` add the user's value as `$input` when they fire the action; `Form` and a `Card` with `asForm` set add an object keyed by each control's `name` instead. On a `Card` there is no Card-level `$action`: the collected object is dispatched through `confirm.$action`, while `cancel.$action` always fires without `$input`. Unknown action types are ignored and warn in development.
 
 ## Streaming
 
@@ -249,3 +250,60 @@ 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).
+
+## Slack Block Kit
+
+`toSlackBlocks` from `@assistant-ui/react-generative-ui/slack` converts a
+generative-UI tree into Slack's Block Kit JSON. It is pure and React-free, so
+it runs equally well in a server action, a queue worker, or a webhook
+handler. Components the converter doesn't recognize are skipped and reported
+as warnings instead of throwing, and content that exceeds Slack's published
+size and count budgets is clamped or downgraded to a simpler block rather
+than producing an invalid payload.
+
+```tsx
+import { WebClient } from "@slack/web-api";
+import { toSlackBlocks } from "@assistant-ui/react-generative-ui/slack";
+
+const slack = new WebClient(process.env.SLACK_BOT_TOKEN);
+
+const { blocks } = toSlackBlocks({
+  $type: "Card",
+  title: "Order #48213",
+  children: [{ $type: "Text", value: "Shipped, arriving Thursday." }],
+});
+
+await slack.chat.postMessage({
+  channel: "#orders",
+  blocks,
+});
+```
+
+Slack posts interactive elements back as a `block_actions` payload.
+`decodeBlockAction` takes one entry from that payload's `actions` array and
+decodes it back into the `$action` shape your tree dispatched, with the
+user's runtime selection (a picked option, a typed value) carried under
+`$input`. Receiving the webhook, verifying its signature, and routing the
+decoded action to your handler stay the host app's responsibility; the
+converter only speaks JSON in and JSON out.
+
+The inverse direction is `fromSlackBlocks`: it maps a Block Kit payload back into vocabulary nodes, back-mapping each element's `action_id` to `$action.type` and reparsing serialized payload values. The round trip is faithful on the plain building blocks (text, images, facts, controls, tables, simple cards) and documented-lossy elsewhere: context elements all return as `Caption`, button styles beyond `primary` and `danger` are dropped, an alert's title and description come back as one description, and card layouts flatten to the fields the `card` block carries.
+
+A few conversion caveats worth knowing:
+
+- `Alert` has no message-surface equivalent upstream (Slack only supports it
+  in modals), so messages get a context block plus section block fallback
+  instead.
+- `Card` and `Carousel` have tight text budgets; a card whose content
+  overflows its budget falls back to plain blocks rather than the card
+  layout.
+- `Chart` has no Slack Block Kit mapping and is replaced by a note block.
+- The Block Kit Builder deep link format
+  (`https://app.slack.com/block-kit-builder/#<payload>`) is an observed
+  convention, not an officially documented API.
+
+## Microsoft Teams
+
+The same tree converts to an Adaptive Card with `toAdaptiveCard` from `@assistant-ui/react-generative-ui/teams`: pure, React-free, pinned to Adaptive Cards 1.5 (the Teams desktop ceiling; mobile clients cap at 1.2), and total in the same way as the Slack converter, so unknown components degrade with warnings instead of failing. Interactive components encode their `$action` inside the submit payload's reserved `aui` key, and `decodeSubmitData` splits a bot's incoming `activity.value` back into the `$action` shape with the card's input values under `$input`. A root `Carousel` is an activity-level construct on Teams, so `toTeamsAttachments` returns up to ten card attachments with `attachmentLayout: "carousel"` instead of one card.
+
+Caveats mirror the platform: Teams ignores positive and destructive action styling, TextBlock markdown is a subset (no headings, tables, or images), `Divider` and `Spacer` become `separator` and `spacing` properties on the following element, and `Chart` has no Teams mapping and is replaced by a note.

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

@@ -298,7 +298,7 @@ function MyRuntimeProvider({ children }) {
 
   useEffect(() => {
     // Set up persistence adapter
-    aui.interactables().setPersistenceAdapter({
+    aui.interactables.setPersistenceAdapter({
       save: async (state) => {
         localStorage.setItem("interactables", JSON.stringify(state));
       },
@@ -307,7 +307,7 @@ function MyRuntimeProvider({ children }) {
     // Restore saved state on mount
     const saved = localStorage.getItem("interactables");
     if (saved) {
-      aui.interactables().importState(JSON.parse(saved));
+      aui.interactables.importState(JSON.parse(saved));
     }
   }, [aui]);
 
@@ -334,10 +334,10 @@ State changes are automatically debounced (500ms) before saving. When a componen
 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
 ```
 

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

@@ -618,7 +618,7 @@ function MyRuntimeProvider({ children }) {
 
 `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 +640,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
 ```
 

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

@@ -69,20 +69,32 @@ The route accepts `POST` requests with `{ method, params }` JSON bodies. Dispatc
 // app/api/mcp-apps/route.ts
 import { createMCPClient } from "@ai-sdk/mcp";
 
-let clientPromise: ReturnType<typeof createMCPClient> | undefined;
-const getClient = () => {
-  clientPromise ??= createMCPClient({
-    transport: { type: "sse", url: process.env.MCP_SERVER_URL! },
-  }).catch((error) => {
-    clientPromise = undefined;
-    throw error;
-  });
+const serverUrls = new Map([
+  ["search", process.env.SEARCH_MCP_SERVER_URL!],
+  ["calendar", process.env.CALENDAR_MCP_SERVER_URL!],
+]);
+const fallbackServerUrl = process.env.MCP_SERVER_URL!;
+const clientPromises = new Map<string, ReturnType<typeof createMCPClient>>();
+
+const getClient = (serverId?: string) => {
+  const url = serverId ? serverUrls.get(serverId) : fallbackServerUrl;
+  if (!url) throw new Error(`Unknown MCP server: ${serverId}`);
+  let clientPromise = clientPromises.get(url);
+  if (!clientPromise) {
+    clientPromise = createMCPClient({
+      transport: { type: "sse", url },
+    }).catch((error) => {
+      clientPromises.delete(url);
+      throw error;
+    });
+    clientPromises.set(url, clientPromise);
+  }
   return clientPromise;
 };
 
 export async function POST(req: Request) {
   const { method, params } = await req.json();
-  const client = await getClient();
+  const client = await getClient(params?.serverId);
 
   switch (method) {
     case "mcp-apps/read-resource": {
@@ -109,8 +121,10 @@ export async function POST(req: Request) {
     }
     case "resources/read":
       return Response.json(await client.readResource({ uri: params.uri }));
-    case "resources/list":
-      return Response.json(await client.listResources(params));
+    case "resources/list": {
+      const { serverId: _, ...listParams } = params ?? {};
+      return Response.json(await client.listResources(listParams));
+    }
     default:
       return Response.json({ error: "Unsupported method" }, { status: 400 });
   }
@@ -119,6 +133,10 @@ export async function POST(req: Request) {
 
 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.
 
+### Multiple MCP servers
+
+When a tool part carries `mcp.app.serverId`, the renderer forwards it to the host operations as `params.serverId` so the route can select the MCP client that owns the resource or tool. The agent stack emits this routable identity in part metadata. For `@ag-ui/mcp-apps-middleware`, assistant-ui uses its configured `serverId`, falling back to `serverHash` when `serverId` is absent or empty. Match the route's map keys to whichever identity your setup emits: configure an explicit `serverId` on each middleware server, or key the map by the emitted hashes. Omitting `serverId` preserves the single-server behavior, as shown by the fallback client in the route example.
+
 Per-name `setToolUI` registrations always win over the MCP fallback — you can still customize specific tools.
 
 ## AI SDK integration
@@ -146,7 +164,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";
@@ -166,7 +184,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;
 };
@@ -186,6 +210,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.

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

@@ -81,7 +81,8 @@ const mcpClient = await createMCPClient({
 
 In a generative toolkit, spread `defineMcpToolkit({ ... })` with one entry per
 MCP server. The entry key names the server connection; the MCP server publishes
-the actual tool names.
+the actual tool names. Use a readable key because it appears in connection,
+tool-listing, and close errors for debugging.
 
 ```tsx title="app/toolkit.tsx"
 "use generative";
@@ -99,6 +100,62 @@ export default defineToolkit({
 });
 ```
 
+Use `{ server, disabled }` when a whole MCP server should stay configured but
+not expose tools for the current request, such as missing credentials, feature
+flags, or plan gating:
+
+```tsx
+defineMcpToolkit({
+  docs: {
+    server: {
+      type: "http",
+      url: process.env.DOCS_MCP_URL!,
+    },
+    disabled: !process.env.DOCS_MCP_URL,
+  },
+});
+```
+
+Use `tools` when the server should stay enabled but specific MCP tools should
+be hidden from the model:
+
+```tsx
+defineMcpToolkit({
+  docs: {
+    server: {
+      type: "http",
+      url: process.env.DOCS_MCP_URL!,
+    },
+    tools: {
+      deleteDocument: {
+        disabled: !userCanDelete,
+      },
+    },
+  },
+});
+```
+
+If multiple MCP servers expose the same tool name, wrap the entry with
+`{ server, prefix }` to give each server's tools distinct model-visible names:
+
+```tsx
+export default defineToolkit({
+  ...defineMcpToolkit({
+    docs: {
+      server: { type: "http", url: "https://docs.example.com/mcp" },
+      prefix: "docs_",
+    },
+    github: {
+      server: { type: "http", url: "https://github.example.com/mcp" },
+      prefix: "github_",
+    },
+  }),
+});
+```
+
+If both servers publish `search`, the model receives `docs_search` and
+`github_search` instead of an ambiguous duplicate.
+
 Use `AISDKToolkit` in the route. It opens the MCP clients, merges their tools
 with the rest of your toolkit, and closes them when you call `close()`:
 
@@ -319,7 +376,7 @@ import type { ReactNode } from "react";
 import { toolkit } from "./GitHubIssueToolUI";
 
 export function MyRuntimeProvider({ children }: { children: ReactNode }) {
-  const runtime = useChatRuntime({ api: "/api/chat" });
+  const runtime = useChatRuntime();
   const aui = useAui({ tools: Tools({ toolkit }) });
 
   return (
@@ -330,6 +387,46 @@ export function MyRuntimeProvider({ children }: { children: ReactNode }) {
 }
 ```
 
+`useChatRuntime()` targets `/api/chat` by default. To point at a different endpoint or customize requests, see [Custom transport](/docs/runtimes/ai-sdk/v7#custom-transport).
+
+</Step>
+<Step>
+
+### Require approval before an MCP tool runs
+
+MCP tools execute on the server, so approval is a server-side tool gate, not a `humanTool()` result. Gate the call with AI SDK v7's call-level `toolApproval` option, keyed by the tool's model-visible name. The tool name stays the same, so your custom renderer or the default `ToolFallback` receives `approval` and `respondToApproval` like any other backend tool:
+
+```ts title="app/api/chat/route.ts"
+const tools = await mcpClient.tools();
+
+const result = streamText({
+  model: openai("gpt-5.4-mini"),
+  messages: await convertToModelMessages(messages),
+  tools,
+  toolApproval: {
+    github_delete_repository: "user-approval",
+  },
+  onFinish: async () => {
+    await mcpClient.close();
+  },
+});
+```
+
+With `AISDKToolkit`, pass the same `toolApproval` option alongside the tools returned by `await aiToolkit.tools(...)`; key it by the prefixed name when the entry sets one.
+
+On the client, let the AI SDK send the recorded approval decision back to the
+route:
+
+```tsx title="app/components/RuntimeProvider.tsx"
+import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
+
+const runtime = useChatRuntime({
+  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
+});
+```
+
+Use this pattern for backend-owned actions such as deleting, writing, deploying, or calling privileged MCP tools. Use `humanTool()` only when the user supplies the tool result itself. For custom approval UIs, see [Server-side approval gates](/docs/tools/tool-ui#server-side-approval-gates); for the full wire setup, see [Server-side tool approval](/docs/runtimes/ai-sdk/v7#server-side-tool-approval).
+
 </Step>
 <Step>
 
@@ -357,7 +454,7 @@ Start the app and trigger a tool call (e.g., ask the assistant to do something t
   <Card
     title="AI SDK runtime"
     description="The runtime that ferries MCP tool calls to the chat UI."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
   <Card
     title="Tools and tool UI"

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

@@ -74,7 +74,7 @@ import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import toolkit from "./toolkit";
 
 function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
-  const runtime = useChatRuntime({ api: "/api/chat" });
+  const runtime = useChatRuntime();
   const aui = useAui({ tools: Tools({ toolkit }) });
   return (
     <AssistantRuntimeProvider aui={aui} runtime={runtime}>
@@ -84,6 +84,8 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 }
 ```
 
+`useChatRuntime()` targets `/api/chat` by default. To point at a different endpoint or customize requests, see [Custom transport](/docs/runtimes/ai-sdk/v7#custom-transport).
+
 <Callout type="tip">
   Frontend toolkit entries can be passed to your backend using the
   `frontendTools` utility.
@@ -537,7 +539,7 @@ export default defineToolkit({
 
 ### Server-side approval gates
 
-Some runtimes (notably AI SDK v6's `needsApproval` tools) pause on the server and emit an approval request that the client must acknowledge before the tool runs. assistant-ui surfaces this on the tool part as `approval` and exposes `respondToApproval({ approved, reason? })` on the renderer:
+Some runtimes (notably AI SDK v7's `toolApproval`-gated tools) pause on the server and emit an approval request that the client must acknowledge before the tool runs. assistant-ui surfaces this on the tool part as `approval` and exposes `respondToApproval({ approved, reason? })` on the renderer:
 
 ```tsx
 const toolkit = defineToolkit({
@@ -581,9 +583,9 @@ const toolkit = defineToolkit({
 
 `approval.isAutomatic` is `true` when the runtime granted the decision from a server-side policy rather than the user; render a "auto-approved" badge instead of buttons in that case.
 
-Approval gates require a runtime that implements them: the AI SDK v6 runtime emits them for `needsApproval` tools, and `LocalRuntime` supports gates emitted by your `ChatModelAdapter`; see [LocalRuntime approval gates](/docs/runtimes/custom/local-runtime#approval-gates). For tools where the user supplies the result itself, use `unstable_humanToolNames` with `addResult` instead; see [human-in-the-loop tools](/docs/runtimes/custom/local-runtime#human-in-the-loop-tools).
+Approval gates require a runtime that implements them: the AI SDK v7 runtime emits them for `toolApproval`-gated tools, and `LocalRuntime` supports gates emitted by your `ChatModelAdapter`; see [LocalRuntime approval gates](/docs/runtimes/custom/local-runtime#approval-gates). For tools where the user supplies the result itself, use `unstable_humanToolNames` with `addResult` instead; see [human-in-the-loop tools](/docs/runtimes/custom/local-runtime#human-in-the-loop-tools).
 
-For the wire-side setup (`needsApproval`, `sendAutomaticallyWhen`), see [AI SDK v6 server-side tool approval](/docs/runtimes/ai-sdk/v6#server-side-tool-approval).
+For the wire-side setup (`needsApproval`, `sendAutomaticallyWhen`), see [AI SDK v7 server-side tool approval](/docs/runtimes/ai-sdk/v7#server-side-tool-approval).
 
 ### Approval options
 

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

@@ -114,7 +114,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 +179,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>
@@ -221,14 +221,13 @@ import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 
 export function Chat() {
   const runtime = useChatRuntime({
-    api: "/api/chat",
     sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
   });
   /* … */
 }
 ```
 
-`sendAutomaticallyWhen` sends completed frontend tool results back to the server so the model can continue after a tool call.
+`sendAutomaticallyWhen` sends completed frontend tool results back to the server so the model can continue after a tool call. `useChatRuntime()` targets `/api/chat` by default; to point at a different endpoint, see [Custom transport](/docs/runtimes/ai-sdk/v7#custom-transport).
 
 Tool names are prefixed `serverId__toolName` to avoid collisions across connected servers. The toolkit re-registers whenever a server connects / disconnects or its tool list changes.
 
@@ -237,12 +236,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:
@@ -313,9 +356,32 @@ 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 = {
+  resources: Array<{ uri: string; name?: string }>;
+  nextCursor?: string;
+};
+
+const server = aui.mcp.server({ id });
+const resources: ResourcePage["resources"] = [];
+let nextCursor: string | undefined;
+
+do {
+  const page = (await (nextCursor === undefined
+    ? server.listResources()
+    : server.listResources({ cursor: nextCursor }))) as ResourcePage;
+  resources.push(...page.resources);
+  nextCursor = page.nextCursor;
+} while (nextCursor !== undefined);
+
+const firstResource = resources[0];
+if (firstResource) {
+  const preview = await server.readResource(firstResource.uri);
+}
 ```
 
 ## v1 scope
@@ -323,13 +389,15 @@ await aui.mcp().server({ id }).callTool("echo", { text: "hi" });
 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
 
 What's deferred:
 
-- Resources, prompts, sampling
+- Prompts, sampling
 - Auto-reconnect with backoff
 - Per-tool enable/disable persistence
 - Per-tool consent prompts