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

package/.docs/raw/docs/runtimes/concepts/adapters.mdx

@@ -196,7 +196,7 @@ type ThreadHistoryAdapter = {
 `load` runs when a thread opens. `append` runs after each message completes.
 
 <Callout type="info">
-`react-ai-sdk` requires `withFormat` so messages round-trip as AI SDK `UIMessage` objects. An adapter without `withFormat` throws at runtime in the AI SDK path. See the [AI SDK history docs](/docs/runtimes/ai-sdk/v6) for the full pattern.
+`react-ai-sdk` requires `withFormat` so messages round-trip as AI SDK `UIMessage` objects. An adapter without `withFormat` throws at runtime in the AI SDK path. See the [AI SDK history docs](/docs/runtimes/ai-sdk/v7) for the full pattern.
 </Callout>
 
 ## Suggestion adapter

package/.docs/raw/docs/runtimes/concepts/architecture.mdx

@@ -118,7 +118,7 @@ The fastest path. Each adapter wraps one of the core or protocol layers and adds
 
 | Adapter | Layered on | Targets |
 | --- | --- | --- |
-| `react-ai-sdk` | `ExternalStoreRuntime` | Vercel AI SDK v6 (`useChat`) |
+| `react-ai-sdk` | `ExternalStoreRuntime` | Vercel AI SDK v7 (`useChat`) |
 | `react-langgraph` | `ExternalStoreRuntime` | LangGraph Cloud via `@langchain/langgraph-sdk` |
 | `react-langchain` | `ExternalStoreRuntime` | LangGraph Cloud via `@langchain/react`'s `useStream` |
 | `react-google-adk` | `ExternalStoreRuntime` | Google ADK JS or Python agents |

package/.docs/raw/docs/runtimes/custom/data-stream.mdx

@@ -19,14 +19,17 @@ If your backend exposes a richer state surface, consider [`AssistantTransport`](
 
 ## Wire protocols
 
-`useDataStreamRuntime` accepts two wire formats via its `protocol` option:
+`useDataStreamRuntime` accepts two wire formats. When `protocol` is omitted, it
+detects known Vercel AI response markers before falling back to UI message
+stream for compatibility.
 
-| Protocol | Default | Matching backend |
+| Protocol | Detection | Matching backend |
 | --- | --- | --- |
-| `"ui-message-stream"` | yes | AI SDK v6's `result.toUIMessageStreamResponse()` (SSE) |
-| `"data-stream"` | no | `createAssistantStreamResponse` from `assistant-stream`, or AI SDK v4's `toDataStreamResponse()` (Vercel data stream v1) |
+| `"ui-message-stream"` | `x-vercel-ai-ui-message-stream: v1`, otherwise fallback | AI SDK v5+'s `result.toUIMessageStreamResponse()` (SSE) |
+| `"data-stream"` | `x-vercel-ai-data-stream: v1` | `createAssistantStreamResponse` from `assistant-stream`, or AI SDK v4's `toDataStreamResponse()` (Vercel data stream v1) |
 
-Pairing the default decoder with a data stream backend throws `Stream ended abruptly without receiving [DONE] marker` at flush; pass `protocol: "data-stream"` to switch decoders.
+Set `protocol` explicitly only for custom endpoints that do not preserve or
+expose the response marker.
 
 ## Install
 
@@ -66,10 +69,7 @@ import { AssistantRuntimeProvider } from "@assistant-ui/react";
 import { Thread } from "@/components/assistant-ui/thread";
 
 export default function ChatPage() {
-  const runtime = useDataStreamRuntime({
-    api: "/api/chat",
-    protocol: "data-stream",
-  });
+  const runtime = useDataStreamRuntime({ api: "/api/chat" });
   return (
     <AssistantRuntimeProvider runtime={runtime}>
       <Thread />
@@ -90,10 +90,7 @@ import { Thread } from "@/components/assistant-ui/thread";
 const API_URL = process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:3000";
 
 export default function ChatPage() {
-  const runtime = useDataStreamRuntime({
-    api: `${API_URL}/api/chat`,
-    protocol: "data-stream",
-  });
+  const runtime = useDataStreamRuntime({ api: `${API_URL}/api/chat` });
   return (
     <AssistantRuntimeProvider runtime={runtime}>
       <View style={{ flex: 1 }}>
@@ -116,7 +113,6 @@ import { Thread } from "./components/thread.js";
 export function App() {
   const runtime = useDataStreamRuntime({
     api: "http://localhost:3000/api/chat",
-    protocol: "data-stream",
   });
   return (
     <AssistantRuntimeProvider runtime={runtime}>
@@ -167,7 +163,6 @@ The request body includes `messages`, `tools`, `system` (if configured), and `th
 ```tsx
 const runtime = useDataStreamRuntime({
   api: "/api/chat",
-  protocol: "data-stream",
   headers: { Authorization: `Bearer ${token}`, "X-Custom-Header": "value" },
   credentials: "include",
 });
@@ -178,7 +173,6 @@ Evaluate per-request:
 ```tsx
 const runtime = useDataStreamRuntime({
   api: "/api/chat",
-  protocol: "data-stream",
   headers: async () => ({
     Authorization: `Bearer ${await getAuthToken()}`,
   }),
@@ -195,7 +189,6 @@ const runtime = useDataStreamRuntime({
 ```tsx
 const runtime = useDataStreamRuntime({
   api: "/api/chat",
-  protocol: "data-stream",
   onResponse: (response) => console.log("status:", response.status),
   onFinish: (message) => console.log("done:", message),
   onError: (error) => console.error(error),
@@ -230,7 +223,6 @@ const myTools = {
 
 const runtime = useDataStreamRuntime({
   api: "/api/chat",
-  protocol: "data-stream",
   body: { tools: toToolsJSONSchema(myTools) },
 });
 ```
@@ -291,7 +283,6 @@ const runtime = useCloudRuntime({
 ```tsx
 const runtime = useDataStreamRuntime({
   api: "/api/chat",
-  protocol: "data-stream",
   initialMessages: [
     { role: "user", content: [{ type: "text", text: "Hello" }] },
     { role: "assistant", content: [{ type: "text", text: "Hi!" }] },

package/.docs/raw/docs/runtimes/custom/external-store.mdx

@@ -796,7 +796,7 @@ useExternalStoreRuntime({
       name: "onResume",
       type: "(config: ResumeRunConfig) => Promise<void>",
       description:
-        "Handler for resuming an interrupted run (e.g. after a page reload mid-generation).",
+        "Handler for resuming an interrupted run (e.g. after a page reload mid-generation). For AI SDK reload-safe streaming, see the [Resumable Streams](/docs/guides/resumable-streams) guide.",
     },
     {
       name: "onResumeToolCall",

package/.docs/raw/docs/runtimes/custom/local-runtime.mdx

@@ -698,6 +698,8 @@ const OpenAIAdapter: ChatModelAdapter = {
 };
 ```
 
+For local development on a ChatGPT Plus or Pro plan, the same client can run without a real API key by pointing `baseURL` at a local OAuth proxy and passing a placeholder `apiKey`; see [ChatGPT Subscription](/docs/guides/chatgpt-subscription#openai-compatible-proxy).
+
 ### Custom REST API
 
 ```tsx

package/.docs/raw/docs/runtimes/eve/overview.mdx

@@ -56,7 +56,7 @@ export default function Home() {
 - An Eve app mounted with `eve/next`.
 - A model credential for the model configured in `agent/agent.ts`.
 
-Eve's default gateway model ids route through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). Use `AI_GATEWAY_API_KEY` or Vercel OIDC, or configure a direct provider `LanguageModel`.
+Eve's default gateway model ids route through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). Use `AI_GATEWAY_API_KEY` or Vercel OIDC, or configure a direct provider `LanguageModel`. For local development, a direct `LanguageModel` can also run on a ChatGPT Plus or Pro plan without any API key; see [ChatGPT Subscription](/docs/guides/chatgpt-subscription).
 
 ## Install
 

package/.docs/raw/docs/runtimes/langgraph/agent-state.mdx

@@ -0,0 +1,181 @@
+---
+title: Agent state
+description: Read and optimistically update graph state with useLangGraphState and useLangGraphSetState in LangGraph.
+---
+
+`useLangGraphState` mirrors the graph's values object that LangGraph streams to the client. It updates live while the agent runs (when the `values` stream mode is enabled). `useLangGraphSetState` lets you apply optimistic local updates that ride the next send.
+
+## Enable the `values` stream mode
+
+<Callout type="warn">
+The default stream setup does **not** include the `values` stream mode. Without it, `useLangGraphState` never receives live graph state.
+</Callout>
+
+When you call `client.runs.stream` yourself, request `values` alongside the modes you already use:
+
+```ts
+client.runs.stream(threadId, assistantId, {
+  input,
+  streamMode: ["messages", "updates", "custom", "values"],
+});
+```
+
+If you use `unstable_createLangGraphStream`, its default stream modes do **not** include `values` either. Pass the option explicitly:
+
+```ts
+const stream = unstable_createLangGraphStream({
+  client,
+  assistantId: ASSISTANT_ID,
+  streamMode: ["messages", "updates", "custom", "values"],
+});
+```
+
+## Basic usage
+
+```tsx
+import {
+  useLangGraphState,
+  useLangGraphSetState,
+} from "@assistant-ui/react-langgraph";
+import { useAuiState } from "@assistant-ui/react";
+
+type GraphState = {
+  messages: unknown[];
+  filters: { region: string; maxResults: number };
+};
+
+const state = useLangGraphState<GraphState>();
+// state: GraphState | undefined  (latest agent state; updates live while the agent runs)
+
+const setState = useLangGraphSetState<GraphState>();
+// setState(next | (prev) => next)   (optimistic local update; sent with the NEXT run)
+
+const isRunning = useAuiState((s) => s.thread.isRunning);
+// isRunning: boolean                (whether the thread is currently running)
+```
+
+## Example
+
+Render graph state beside the chat and stage an optimistic filter update:
+
+```tsx
+"use client";
+
+import {
+  useLangGraphState,
+  useLangGraphSetState,
+} from "@assistant-ui/react-langgraph";
+import { useAuiState } from "@assistant-ui/react";
+import { Thread } from "@/components/assistant-ui/thread";
+
+type GraphState = {
+  filters: { region: string; maxResults: number };
+  lastQuery?: string;
+};
+
+export function CatalogAssistant() {
+  const state = useLangGraphState<GraphState>();
+  const setState = useLangGraphSetState<GraphState>();
+  const isRunning = useAuiState((s) => s.thread.isRunning);
+
+  return (
+    <div className="flex h-full">
+      <aside className="w-72 border-r p-4">
+        <h2>Graph state</h2>
+        {state ? (
+          <ul>
+            <li>Region: {state.filters.region}</li>
+            <li>Max results: {state.filters.maxResults}</li>
+            {state.lastQuery && <li>Last query: {state.lastQuery}</li>}
+          </ul>
+        ) : (
+          <p>No graph state yet. Ensure streamMode includes "values".</p>
+        )}
+        <button
+          type="button"
+          disabled={isRunning}
+          onClick={() =>
+            setState((prev) => ({
+              ...prev,
+              filters: {
+                region: "eu",
+                maxResults: prev?.filters.maxResults ?? 10,
+              },
+            }))
+          }
+        >
+          Prefer EU region
+        </button>
+        {isRunning && <p>Agent is running…</p>}
+      </aside>
+      <main className="flex-1">
+        <Thread />
+      </main>
+    </div>
+  );
+}
+```
+
+The panel tracks the latest `values` events from the graph. The button updates the local overlay immediately; that update object is merged into the run `input` on the next send so LangGraph applies it through the graph's state reducers and input schema.
+
+## How state is synced
+
+LangGraph state is the graph's values object. When `streamMode` includes `"values"`, each `values` event updates the client-side snapshot that `useLangGraphState` exposes.
+
+The setter from `useLangGraphSetState` overlays that snapshot locally. On the next send, the runtime merges the update object into the run `input`, so LangGraph reduces it through the graph's state reducers and input schema.
+
+If you supply a custom `stream` callback, the staged update is available as `config.state`. Forward it into your run input yourself:
+
+```ts
+const runtime = useLangGraphRuntime({
+  stream: async (messages, { initialize, ...config }) => {
+    const { externalId } = await initialize();
+    if (!externalId) throw new Error("Thread not found");
+
+    const client = createClient();
+    return client.runs.stream(externalId, ASSISTANT_ID, {
+      input: {
+        ...(config.state ?? {}),
+        messages,
+      },
+      streamMode: ["messages", "updates", "custom", "values"],
+    });
+  },
+});
+```
+
+The built-in path that uses the package helpers performs this merge for you. Custom `stream` callbacks must do it explicitly.
+
+## Write-back timing
+
+`useLangGraphSetState` is optimistic and local first. The value reaches the agent only when the next run starts. It is not a live channel into a run that is already in progress. Stage filters, preferences, or other graph fields that the next turn should apply through reducers; do not expect an in-flight run to observe mid-run setter calls.
+
+## Relationship to other state
+
+Keep the three state layers distinct:
+
+- **Your app state** stays yours (React state, URL, a store). assistant-ui does not own it.
+- **`useAuiState`** reads assistant-ui's client state (messages, composer, thread status).
+- **`useLangGraphState` / `useLangGraphSetState`** mirror state the **agent** (your LangGraph graph) owns, synced over the wire via `values` events.
+
+Use `useLangGraphState` and `useLangGraphSetState` for fields that live in the graph state schema. Use `useAuiState` for UI that depends on the chat thread itself. Use your own state for everything else.
+
+## Next
+
+<Cards>
+  <Card
+    title="Streaming"
+    description="Event handlers, message metadata, generative UI."
+    href="/docs/runtimes/langgraph/streaming"
+  />
+  <Card
+    title="Quickstart"
+    description="From-template and manual setup paths."
+    href="/docs/runtimes/langgraph/quickstart"
+  />
+  <Card
+    title="Generative UI"
+    description="Structured UI components emitted by your graph."
+    href="/docs/runtimes/langgraph/generative-ui"
+  />
+</Cards>

package/.docs/raw/docs/tools/backend.mdx

@@ -13,6 +13,8 @@ For authoring tools, see [Defining Tools](/docs/tools/defining-tools). For MCP s
 `@assistant-ui/react-ai-sdk` posts `{ messages, system, tools }` to your route. `tools` is the map of **frontend** tools the client serialized for this request (the model needs their schemas to call them, even though they run in the browser):
 
 ```ts
+import type { FrontendTools } from "@assistant-ui/react-ai-sdk";
+
 const {
   messages,
   system,
@@ -20,7 +22,7 @@ const {
 }: {
   messages: UIMessage[];
   system?: string;
-  tools?: Record<string, { description?: string; parameters: JSONSchema7 }>;
+  tools?: FrontendTools;
 } = await req.json();
 ```
 
@@ -136,9 +138,10 @@ To let the model see a frontend tool's result and continue, configure the runtim
 import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
 
 const runtime = useChatRuntime({
-  api: "/api/chat",
   sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
 });
 ```
 
-For the full AI SDK v6 backend setup — history persistence, reasoning, server-side approvals — see the [AI SDK v6 guide](/docs/runtimes/ai-sdk/v6).
+`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).
+
+For the full AI SDK v7 backend setup — history persistence, reasoning, server-side approvals — see the [AI SDK v7 guide](/docs/runtimes/ai-sdk/v7).

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/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

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"