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

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";
@@ -93,14 +94,75 @@ export default defineToolkit({
     github: {
       type: "http",
       url: "https://mcp.example.com/mcp",
+      connectionTimeout: 10_000,
     },
   }),
 });
 ```
 
+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()`:
 
+`connectionTimeout` is optional and measured in milliseconds. Set it to fail
+the server-side MCP readiness flow (`createMCPClient()` plus `tools()`) before
+a bad URL or hanging local process can stall the route.
+
 ```ts title="app/api/chat/route.ts"
 import { AISDKToolkit } from "@assistant-ui/react-ai-sdk";
 import { openai } from "@ai-sdk/openai";
@@ -314,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 (
@@ -325,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>
 
@@ -352,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

@@ -59,20 +59,28 @@ const connectors = [
     name: "Weather",
     url: "https://mcp.example.com/weather",
     auth: { type: "none" },
+    connectionTimeout: 10_000,
   }),
 ];
 
 export function Providers({ children }: { children: React.ReactNode }) {
-  const aui = useAui({ mcp: McpManagerResource({ connectors }) });
+  const aui = useAui({
+    mcp: McpManagerResource({
+      connectors,
+      connectionTimeout: 15_000,
+    }),
+  });
   return <AuiProvider value={aui}>{children}</AuiProvider>;
 }
 ```
 
-Defaults baked in:
+Defaults and useful options:
 
 - `storage` — `McpLocalStorage()` (override for production; see [Storage](#storage))
 - `oauthRedirectUri` — `${window.location.origin}/mcp/callback`
 - `autoConnect` — `true` (connect on mount when usable auth is persisted)
+- `connectionTimeout` — optional timeout in milliseconds. Set it on the manager as a default or on a connector/custom server to bound the MCP readiness flow (`connect()` plus `listTools()`) with a clear error.
+- Connector `id` values must be unique. The id is used for server lookup, OAuth routing, and model-visible tool names such as `linear__search`.
 
 </Step>
 <Step>
@@ -208,14 +216,19 @@ The callback reads `?state=...&code=...` from the URL, derives the target server
 
 ```tsx
 "use client";
+import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 
 export function Chat() {
-  const runtime = useChatRuntime({ api: "/api/chat" });
+  const runtime = useChatRuntime({
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
+  });
   /* … */
 }
 ```
 
+`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.
 
 If no chat runtime is mounted, `McpManagerResource` brings its own minimal `modelContext` along. Tools are still callable directly:
@@ -302,6 +315,29 @@ const aui = useAui();
 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
@@ -309,13 +345,14 @@ 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
 - 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

package/.docs/raw/docs/ui/accordion.mdx

@@ -2,8 +2,10 @@
 title: Accordion
 description: A vertically stacked set of interactive headings that reveal or hide content sections.
 links:
-  - label: Radix UI Accordion
+  - label: Radix UI Accordion (Radix styles)
     url: https://www.radix-ui.com/primitives/docs/components/accordion
+  - label: Base UI Accordion (base styles)
+    url: https://base-ui.com/react/components/accordion
 platforms: ["react"]
 ---
 
@@ -16,12 +18,16 @@ import {
   AccordionControlledSample,
   AccordionFAQSample,
 } from "@/components/docs/samples/accordion";
+import * as AccordionRadixSamples from "@/components/docs/samples/accordion.radix";
+import { Flavored, FlavorSwitcher } from "@/components/docs/contexts/flavor.server";
 
 <Callout>
   This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
 </Callout>
 
-<AccordionSample />
+<FlavorSwitcher />
+
+<Flavored radix={<AccordionRadixSamples.AccordionSample />} base={<AccordionSample />} />
 
 ## Installation
 
@@ -59,7 +65,7 @@ export function Example() {
 
 Use the `variant` prop on `Accordion` to change the visual style. Child components inherit the variant automatically.
 
-<AccordionVariantsSample />
+<Flavored radix={<AccordionRadixSamples.AccordionVariantsSample />} base={<AccordionVariantsSample />} />
 
 ```tsx
 // Default - border-bottom separator
@@ -91,7 +97,7 @@ Use the `variant` prop on `Accordion` to change the visual style. Child componen
 
 Use `type="multiple"` to allow multiple items to be open simultaneously.
 
-<AccordionMultipleSample />
+<Flavored radix={<AccordionRadixSamples.AccordionMultipleSample />} base={<AccordionMultipleSample />} />
 
 ```tsx
 <Accordion type="multiple">
@@ -110,24 +116,24 @@ Use `type="multiple"` to allow multiple items to be open simultaneously.
 
 Add icons or custom elements inside the trigger.
 
-<PreviewCode file="components/docs/samples/accordion" name="AccordionWithIconsSample">
-  <AccordionWithIconsSample />
+<PreviewCode file="components/docs/samples/accordion" name="AccordionWithIconsSample" base={<AccordionWithIconsSample />}>
+  <AccordionRadixSamples.AccordionWithIconsSample />
 </PreviewCode>
 
 ### Controlled
 
 Use `value` and `onValueChange` for controlled accordion state.
 
-<PreviewCode file="components/docs/samples/accordion" name="AccordionControlledSample">
-  <AccordionControlledSample />
+<PreviewCode file="components/docs/samples/accordion" name="AccordionControlledSample" base={<AccordionControlledSample />}>
+  <AccordionRadixSamples.AccordionControlledSample />
 </PreviewCode>
 
 ### FAQ Section
 
 A practical example of using accordion for a FAQ section.
 
-<PreviewCode file="components/docs/samples/accordion" name="AccordionFAQSample">
-  <AccordionFAQSample />
+<PreviewCode file="components/docs/samples/accordion" name="AccordionFAQSample" base={<AccordionFAQSample />}>
+  <AccordionRadixSamples.AccordionFAQSample />
 </PreviewCode>
 
 ## API Reference

package/.docs/raw/docs/ui/assistant-modal.mdx

@@ -5,10 +5,14 @@ platforms: ["react"]
 ---
 
 import { AssistantModalSample } from "@/components/docs/samples/assistant-modal";
+import * as AssistantModalRadixSamples from "@/components/docs/samples/assistant-modal.radix";
+import { Flavored, FlavorSwitcher } from "@/components/docs/contexts/flavor.server";
 
-A floating chat modal built on Radix UI Popover. Ideal for support widgets, help desks, and embedded assistants.
+A floating chat modal built on the popover primitive of your configured style (Radix UI Popover on Radix styles, Base UI Popover on `base-*` styles). Ideal for support widgets, help desks, and embedded assistants.
 
-<AssistantModalSample />
+<FlavorSwitcher />
+
+<Flavored radix={<AssistantModalRadixSamples.AssistantModalSample />} base={<AssistantModalSample />} />
 
 ## Getting Started
 
@@ -43,7 +47,7 @@ export default function Home() {
 
 ## Anatomy
 
-The `AssistantModal` component is built with the following primitives:
+The Radix flavor of `AssistantModal` is built with the following primitives. The Base UI flavor composes your project's Base UI Popover instead.
 
 ```tsx
 import { AssistantModalPrimitive } from "@assistant-ui/react";
@@ -61,7 +65,7 @@ import { AssistantModalPrimitive } from "@assistant-ui/react";
 
 ### Root
 
-Contains all parts of the modal. Based on Radix UI Popover.
+Contains all parts of the modal when using `AssistantModalPrimitive` (the Radix flavor). The Base UI flavor uses your project's Base UI Popover instead.
 
 <ParametersTable
   type="AssistantModalPrimitiveRootProps"

package/.docs/raw/docs/ui/attachment.mdx

@@ -5,8 +5,12 @@ platforms: ["react"]
 ---
 
 import { AttachmentSample } from "@/components/docs/samples/attachment";
+import * as AttachmentRadixSamples from "@/components/docs/samples/attachment.radix";
+import { Flavored, FlavorSwitcher } from "@/components/docs/contexts/flavor.server";
 
-<AttachmentSample />
+<FlavorSwitcher />
+
+<Flavored radix={<AttachmentRadixSamples.AttachmentSample />} base={<AttachmentSample />} />
 
 <Callout type="info">
   **Note:** These components provide the UI for attachments, but you also need

package/.docs/raw/docs/ui/badge.mdx

@@ -2,8 +2,10 @@
 title: Badge
 description: A small label component for displaying status, categories, or metadata.
 links:
-  - label: Radix UI Slot
+  - label: Radix UI Slot (Radix styles)
     url: https://www.radix-ui.com/primitives/docs/utilities/slot
+  - label: Base UI useRender (base styles)
+    url: https://base-ui.com/react/utils/use-render
 platforms: ["react"]
 ---
 
@@ -15,12 +17,16 @@ import {
   BadgeAsLinkSample,
   BadgeAnimatedSample,
 } from "@/components/docs/samples/badge";
+import * as BadgeRadixSamples from "@/components/docs/samples/badge.radix";
+import { Flavored, FlavorSwitcher } from "@/components/docs/contexts/flavor.server";
 
 <Callout>
   This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
 </Callout>
 
-<BadgeSample />
+<FlavorSwitcher />
+
+<Flavored radix={<BadgeRadixSamples.BadgeSample />} base={<BadgeSample />} />
 
 ## Installation
 
@@ -42,7 +48,7 @@ export function Example() {
 
 Use the `variant` prop to change the visual style.
 
-<BadgeSample />
+<Flavored radix={<BadgeRadixSamples.BadgeSample />} base={<BadgeSample />} />
 
 ```tsx
 <Badge variant="outline" />     // Border (default)
@@ -59,7 +65,7 @@ Use the `variant` prop to change the visual style.
 
 Use the `size` prop to change the badge size.
 
-<BadgeSizesSample />
+<Flavored radix={<BadgeRadixSamples.BadgeSizesSample />} base={<BadgeSizesSample />} />
 
 ```tsx
 <Badge size="sm" />      // Small
@@ -71,24 +77,24 @@ Use the `size` prop to change the badge size.
 
 Badges automatically style SVG icons.
 
-<PreviewCode file="components/docs/samples/badge" name="BadgeWithIconSample">
-  <BadgeWithIconSample />
+<PreviewCode file="components/docs/samples/badge" name="BadgeWithIconSample" base={<BadgeWithIconSample />}>
+  <BadgeRadixSamples.BadgeWithIconSample />
 </PreviewCode>
 
 ### As Link
 
-Use the `asChild` prop to render the badge as a different element, like a link.
+Compose with `render` (Base UI) or `asChild` (Radix) to render the badge as a different element, like a link.
 
-<PreviewCode file="components/docs/samples/badge" name="BadgeAsLinkSample">
-  <BadgeAsLinkSample />
+<PreviewCode file="components/docs/samples/badge" name="BadgeAsLinkSample" base={<BadgeAsLinkSample />}>
+  <BadgeRadixSamples.BadgeAsLinkSample />
 </PreviewCode>
 
 ### Animated
 
 Combine with CSS transitions for scroll and color animations.
 
-<PreviewCode file="components/docs/samples/badge" name="BadgeAnimatedSample">
-  <BadgeAnimatedSample />
+<PreviewCode file="components/docs/samples/badge" name="BadgeAnimatedSample" base={<BadgeAnimatedSample />}>
+  <BadgeRadixSamples.BadgeAnimatedSample />
 </PreviewCode>
 
 ## API Reference
@@ -110,11 +116,16 @@ Combine with CSS transitions for scroll and color animations.
       default: '"default"',
       description: "The size of the badge.",
     },
+    {
+      name: "render",
+      type: "ReactElement | function",
+      description: "Base UI: compose as a different element instead of rendering a span.",
+    },
     {
       name: "asChild",
       type: "boolean",
       default: "false",
-      description: "Merge props with child element instead of rendering a span.",
+      description: "Radix: merge props with a child element instead of rendering a span.",
     },
     {
       name: "className",

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

@@ -0,0 +1,80 @@
+---
+title: Follow-Up Suggestions
+description: Render runtime-generated follow-up prompt chips after an assistant response.
+platforms: ["react"]
+---
+
+import { FollowUpSuggestionsSample } from "@/components/docs/samples/follow-up-suggestions";
+
+<FollowUpSuggestionsSample />
+
+`ThreadFollowupSuggestions` renders the current thread's runtime suggestions as clickable prompt chips. Use it for follow-up prompts that arrive after a response, such as suggested next questions, refinements, or task shortcuts.
+
+<Callout type="info">
+  This component reads from `thread.suggestions`. For static welcome-screen prompts, use `ThreadPrimitive.Suggestions` instead.
+</Callout>
+
+## Getting Started
+
+<Steps>
+  <Step>
+
+### Add `follow-up-suggestions`
+
+<InstallCommand shadcn={["follow-up-suggestions"]} />
+
+This adds a `/components/assistant-ui/follow-up-suggestions.tsx` file to your project. The default `thread` component already renders `ThreadFollowupSuggestions`, so installing it standalone is only needed when you build your own thread layout.
+
+  </Step>
+  <Step>
+
+### Provide runtime suggestions
+
+Pass suggestions through your runtime. External-store runtimes, AI SDK runtimes, and local runtimes can all surface follow-up prompts through `thread.suggestions`.
+
+```tsx title="/app/assistant.tsx" {7-10}
+const runtime = useExternalStoreRuntime({
+  messages,
+  convertMessage,
+  onNew: async (message) => {
+    // append the message in your store
+  },
+  suggestions: [
+    { prompt: "Summarize this as action items" },
+    { prompt: "Write a shorter version" },
+  ],
+});
+```
+
+  </Step>
+  <Step>
+
+### Render after messages
+
+Place `ThreadFollowupSuggestions` near the bottom of your thread viewport, after the assistant message list and before the composer.
+
+```tsx title="/components/assistant-ui/thread.tsx" {1,10}
+import { ThreadFollowupSuggestions } from "@/components/assistant-ui/follow-up-suggestions";
+
+const ThreadViewportFooter = () => {
+  return (
+    <ThreadPrimitive.ViewportFooter>
+      <ThreadPrimitive.ScrollToBottom />
+      <ThreadFollowupSuggestions />
+      <Composer />
+    </ThreadPrimitive.ViewportFooter>
+  );
+};
+```
+
+  </Step>
+</Steps>
+
+## Behavior
+
+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.
+
+## Related Components
+
+- [Thread](/docs/ui/thread) - Complete chat interface with message list and composer
+- [Suggestions guide](/docs/guides/suggestions) - Runtime and static suggestion patterns