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

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>
   );
@@ -64,9 +66,10 @@ 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.
+  The deprecated [`interactables:
+  Interactables()`](/docs/api-reference/tools/interactables-legacy) scope and the
+  new `unstable_interactables: unstable_Interactables()` scope are mutually
+  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 +169,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 +202,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 +595,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 +614,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.unstable_interactables.setPersistenceAdapter(adapter)` imperatively instead. Replacing or removing an adapter flushes queued changes through the outgoing adapter before the new persistence context is attached.
 
 ### Sync Status
 
@@ -700,7 +712,7 @@ Inside a thread-scoped `render`, `streaming: true` carries the same live state:
 
 ## Multiple Instances
 
-A `name` can have many live instances at once. They all share one `update_{name}` tool: the model addresses an instance with the tool's `id` parameter, which it reads from the state snapshots in the conversation. The tool's name, schema, and description never change as instances mount and unmount, so the model's tool list (and provider prompt caches) stay stable. While exactly one instance exists, the model may omit `id`; a call with an unknown `id` returns an error listing the valid ids, so the model can recover.
+A `name` can have many live instances at once. They all share one `update_{name}` tool: the model addresses an instance with the tool's `id` parameter, which it reads from the state snapshots in the conversation. The tool's name, schema, and description never change as instances mount and unmount, so the model's tool list (and provider prompt caches) stay stable. The schema marks `id` as required, so the model is expected to send it on every call; the runtime still resolves an id-less call while exactly one instance exists. A call with an unknown `id` returns an error listing the valid ids, so the model can recover.
 
 How instances come into being differs by scope.
 
@@ -1040,10 +1052,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,
   // ...
 });
@@ -314,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/openui.mdx

@@ -0,0 +1,175 @@
+---
+title: OpenUI
+description: Render streaming OpenUI Lang interfaces in an assistant-ui conversation with @openuidev/assistant-ui, the integration package published by OpenUI.
+platforms: ["react"]
+---
+
+[OpenUI](https://www.openui.com) is a generative UI system in which the model writes **OpenUI Lang**, a streaming markup language, and an OpenUI renderer turns it into interactive React components. [`@openuidev/assistant-ui`](https://www.npmjs.com/package/@openuidev/assistant-ui) connects that renderer to assistant-ui: it ships a ready-made toolkit, model instructions generated from the OpenUI component library, and Tool UI renderers that stream, handle interactions, and replay.
+
+<Callout type="info">
+  `@openuidev/assistant-ui` is a third-party package. OpenUI owns the package, its [documentation](https://www.openui.com/docs/api-reference/assistant-ui), and its releases; assistant-ui does not ship or version any OpenUI code. Use OpenUI's reference for the package API and OpenUI Lang itself; this page covers the assistant-ui side of the wiring.
+</Callout>
+
+The integration rides entirely on the [Tool UI](/docs/tools/tool-ui) lifecycle, so assistant-ui stays in charge of the conversation, streaming, and tool calls. The toolkit registers two standalone tools:
+
+- `present_openui` is a **frontend tool** for display-only interfaces (cards, tables, charts). It completes as soon as the streamed `ui` argument is available, and the turn ends there.
+- `prompt_openui` is a **human tool** for forms and choices. It completes only when the user submits an OpenUI `@ToAssistant(...)` action, and the submitted values continue the conversation.
+
+## How it relates to the `present` tool
+
+assistant-ui's first-party [Generative UI](/docs/tools/generative-ui) follows the same shape: one tool, a component vocabulary, and a model that composes an interface at runtime. The difference is the representation and who owns it. `present` takes a JSON tree validated against a schema generated from a vocabulary you ship and restyle; `present_openui` takes an OpenUI Lang program rendered by OpenUI's component kit, taught to the model through instructions. Pick `present` when you want the interface built from your own components on assistant-ui's append-only surface, and OpenUI when you are already invested in the OpenUI ecosystem or want its renderer and component library.
+
+## Quick start
+
+The complete setup below runs in [`examples/with-openui`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-openui). To scaffold a standalone copy, run `npx assistant-ui create my-app --example with-openui`.
+
+<Steps>
+
+<Step>
+
+### Install the packages
+
+Alongside an existing `@assistant-ui/react` setup, add the integration and its OpenUI peer dependencies:
+
+<InstallCommand npm={["@openuidev/assistant-ui", "@openuidev/react-ui", "@openuidev/react-lang", "@openuidev/react-headless", "zustand@^4.5.5"]} />
+
+The package also expects `zod` and React 18 or 19, which an assistant-ui app already has. The current OpenUI peers support AI SDK 6 and 7 and require Zustand 4.
+
+</Step>
+
+<Step>
+
+### Load the OpenUI stylesheet
+
+Import the layered stylesheet once, for example in `app/globals.css`:
+
+```css
+@import "@openuidev/react-ui/layered/styles/index.css";
+```
+
+</Step>
+
+<Step>
+
+### Register the toolkit and instructions
+
+`openuiIntegration` bundles a toolkit and an instruction string created from the same OpenUI component library, so the model and the renderer share one vocabulary. Register the toolkit with [`Tools`](/docs/api-reference/tools) and mount `OpenUIInstructions` so the vocabulary reaches the model as assistant instructions:
+
+```tsx title="app/page.tsx"
+"use client";
+
+import {
+  AssistantRuntimeProvider,
+  AuiConfig,
+  Tools,
+} from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { OpenUIInstructions, openuiIntegration } from "@openuidev/assistant-ui";
+import { shouldContinueAfterOpenUIPrompt } from "@openuidev/assistant-ui/ai-sdk";
+import { Thread } from "@/components/assistant-ui/thread";
+
+export default function Home() {
+  const runtime = useChatRuntime({
+    sendAutomaticallyWhen: shouldContinueAfterOpenUIPrompt,
+  });
+
+  const config = AuiConfig({
+    tools: Tools({ toolkit: openuiIntegration.toolkit }),
+  });
+
+  return (
+    <AssistantRuntimeProvider config={config} runtime={runtime}>
+      <OpenUIInstructions />
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+`sendAutomaticallyWhen` is the continuation gate. OpenUI's predicate continues the run only after `prompt_openui` has received a submitted result, so a display-only `present_openui` call ends the turn instead of triggering an empty follow-up request.
+
+<Callout type="info">
+  `sendAutomaticallyWhen` is a single slot. OpenUI's predicate is a strict refinement of `lastAssistantMessageIsCompleteWithToolCalls` (the predicate the other guides in this section use), so it replaces it cleanly when OpenUI's tools are the only ones that resume the run. If your app mixes in other tools whose flows must also resume, write one predicate that decides by tool name; a naive `||` with the generic predicate collapses to the generic predicate alone and re-enables the empty follow-up after display-only calls.
+</Callout>
+
+</Step>
+
+<Step>
+
+### Forward the tools in your API route
+
+The default `AssistantChatTransport` forwards the registered instructions and both frontend tool schemas to the backend, so the route stays generic:
+
+```ts title="app/api/chat/route.ts"
+import { openai } from "@ai-sdk/openai";
+import { frontendTools } from "@assistant-ui/react-ai-sdk";
+import {
+  type JSONSchema7,
+  streamText,
+  convertToModelMessages,
+  type UIMessage,
+  createUIMessageStreamResponse,
+  toUIMessageStream,
+} from "ai";
+
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const {
+    messages,
+    system,
+    tools,
+  }: {
+    messages: UIMessage[];
+    system?: string;
+    tools?: Record<string, { description?: string; parameters: JSONSchema7 }>;
+  } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-5.6-luna"),
+    messages: await convertToModelMessages(messages),
+    ...(system ? { system } : {}),
+    tools: frontendTools(tools ?? {}),
+  });
+
+  return createUIMessageStreamResponse({
+    stream: toUIMessageStream({ stream: result.stream }),
+  });
+}
+```
+
+</Step>
+
+</Steps>
+
+## Interaction and replay
+
+When the user submits a `prompt_openui` form or choice, the integration reports the action, message, parameters, and form state through the standard human-tool `addResult`, and `sendAutomaticallyWhen` resumes the run with that result. On replay of a persisted thread, the stored result hydrates the submitted form state back into the renderer, so completed forms render as submitted instead of resetting.
+
+<Callout type="tip">
+  The core integration is runtime-agnostic: the toolkit, renderers, and instructions work with any assistant-ui runtime that forwards tool schemas and results. Only the `shouldContinueAfterOpenUIPrompt` helper on the `/ai-sdk` subpath is AI SDK-specific.
+</Callout>
+
+## Customization
+
+`createOpenUIIntegration` keeps a custom component library, tool names, and renderer options aligned across the toolkit and the instructions:
+
+```tsx
+import { createOpenUIIntegration } from "@openuidev/assistant-ui";
+import { library } from "./library";
+
+const openui = createOpenUIIntegration({
+  library,
+  presentToolName: "show_panel",
+  promptToolName: "ask_panel",
+});
+```
+
+The result exposes `toolkit`, `instructions`, and the resolved `toolNames`. See [OpenUI's integration reference](https://www.openui.com/docs/api-reference/assistant-ui) for the full option surface, including custom descriptions, prompt options, renderer props, and error handling.
+
+## Related
+
+- [`examples/with-openui`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-openui): the runnable setup from this page
+- [OpenUI assistant-ui integration reference](https://www.openui.com/docs/api-reference/assistant-ui): the canonical package documentation
+- [Generative UI](/docs/tools/generative-ui): the first-party `present` tool this integration sits alongside
+- [Tool UI](/docs/tools/tool-ui): the lifecycle both OpenUI tools build on

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

@@ -21,8 +21,7 @@ Tool UIs in assistant-ui allow you to create custom interfaces that appear when
 
 This guide demonstrates building tool UIs with the **Vercel AI SDK**.
 
-For composing UI from a JSON spec and component allowlist (display-only layouts),
-see the [Generative UI primitive guide](/docs/tools/generative-ui).
+To let the model compose UI from a vocabulary instead of binding one component per tool, see [Generative UI](/docs/tools/generative-ui).
 
 ## Creating Tool UIs
 
@@ -69,15 +68,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 +189,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 +213,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 +329,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 +390,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 +940,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,18 @@ 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.
+
+<Callout type="info">
+The [2026-07-28 spec revision](https://modelcontextprotocol.io/specification/2026-07-28/changelog) deprecates RFC 7591 dynamic client registration in favor of [Client ID Metadata Documents](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents), which clients should prefer over DCR when the authorization server advertises `client_id_metadata_document_supported`. Dynamic client registration remains available for backwards compatibility with authorization servers that do not support CIMD, and the spec's deprecation policy sets a minimum twelve-month window before removal, so the flow described here keeps working. Against a CIMD-only authorization server that exposes no `registration_endpoint`, supply a pre-registered [`clientId`](#auth) instead.
+</Callout>
 
 ## Setup
 
@@ -38,12 +42,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 +68,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>
+  );
 }
 ```
 
@@ -297,7 +306,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({
@@ -336,7 +345,7 @@ Three modes, declared per-connector or per-custom-record:
 }
 ```
 
-The OAuth provider implements the MCP SDK's `OAuthClientProvider`. The SDK handles discovery (RFC 8414), DCR (RFC 7591), PKCE, token exchange, and refresh; this package mediates `MCPStorage` reads/writes and the redirect step. The server id is embedded in the OAuth `state` parameter so a single `/mcp/callback` route knows which server to complete.
+The OAuth provider implements the MCP SDK's `OAuthClientProvider`. The SDK handles discovery (RFC 8414), DCR (RFC 7591 — [deprecated in favor of CIMD](#how-it-works) but still supported), PKCE, token exchange, and refresh; this package mediates `MCPStorage` reads/writes and the redirect step. The server id is embedded in the OAuth `state` parameter so a single `/mcp/callback` route knows which server to complete.
 
 ## State & methods