@assistant-ui/mcp-docs-server 0.1.36 → 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/google-adk/quickstart.mdx

@@ -3,7 +3,7 @@ title: Quickstart
 description: Minimal API route and client setup with createAdkApiRoute.
 ---
 
-Four steps to a working ADK chat. Assumes you have already installed the package and have ADK ready on the server side; if not, start at [overview](/docs/runtimes/google-adk).
+Four steps to a working ADK chat. Assumes you have already installed the package and have ADK ready on the server side; if not, start at [overview](/docs/runtimes/google-adk/overview).
 
 <Steps>
 <Step>

package/.docs/raw/docs/runtimes/langchain.mdx

@@ -5,7 +5,7 @@ description: Use LangChain's useStream hook with a React chat UI through assista
 
 import { LangGraphIcon } from "@/components/icons/langgraph";
 
-`@assistant-ui/react-langchain` wraps [`useStream`](https://docs.langchain.com/oss/javascript/langgraph-sdk/react-stream) from `@langchain/react` and exposes it as an assistant-ui runtime. It targets the same backend as [`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph) (LangGraph Cloud) but at a higher level, delegating stream plumbing to the upstream hook.
+`@assistant-ui/react-langchain` wraps [`useStream`](https://docs.langchain.com/oss/javascript/langgraph-sdk/react-stream) from `@langchain/react` and exposes it as an assistant-ui runtime. It targets the same backend as [`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph/overview) (LangGraph Cloud) but at a higher level, delegating stream plumbing to the upstream hook.
 
 ## When to use it
 
@@ -891,7 +891,7 @@ Regenerate works without configuration. Clicking regenerate resolves the server
     icon={<LangGraphIcon width={20} height={20} className="text-[#1C3C3C] dark:text-[#5b9595]" />}
     title="LangGraph"
     description="The original LangGraph adapter, built on the raw SDK."
-    href="/docs/runtimes/langgraph"
+    href="/docs/runtimes/langgraph/overview"
   />
   <Card
     title="ExternalStoreRuntime"

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/runtimes/opencode/hooks.mdx

@@ -175,7 +175,7 @@ These are only needed for advanced cases; most apps should use `useOpenCodeRunti
     icon={<OpenCodeIcon width={20} height={20} />}
     title="OpenCode overview"
     description="What OpenCode is and when to pick it."
-    href="/docs/runtimes/opencode"
+    href="/docs/runtimes/opencode/overview"
   />
   <Card
     title="Quickstart"

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>
 
@@ -427,6 +429,11 @@ The compiler checks static tool names across inline entries and compiler-visible
 spreads. If two fragments define the same tool name, the build warns that
 JavaScript object spread will keep the later tool definition.
 
+If the compiler reports that `tool "weather" cannot be makeTool()`, that entry
+came from an opaque factory call. Rewrite it as an inline tool object, or spread
+a compiler-visible `defineToolkit(...)` / `defineMcpToolkit(...)` fragment
+instead.
+
 ### Add MCP server tools
 
 `defineMcpToolkit` exposes tools from an MCP server. For an MCP-only toolkit, export it directly:
@@ -456,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

@@ -166,6 +166,44 @@ type GenerativeUISpec = {
 The spec is plain JSON — easy for any agent to emit, and easy to validate
 on the server before delivery.
 
+## Actions with `JSONGenerativeUI`
+
+When you expose a component library through `new JSONGenerativeUI(...)`, pass an
+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,
+  createActionRegistry,
+  defaultGenerativeUILibrary,
+} from "@assistant-ui/react-generative-ui";
+
+const actions = createActionRegistry({
+  purchase: async ({ payload }) => {
+    await checkout(payload);
+  },
+});
+
+const generative = new JSONGenerativeUI({
+  library: defaultGenerativeUILibrary,
+  actions,
+});
+```
+
+```json
+{
+  "$type": "Button",
+  "label": "Buy",
+  "$action": { "type": "purchase", "sku": "pro-plan" }
+}
+```
+
+`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
 
 When a message contains native `generative-ui` parts whose `spec` updates
@@ -212,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

@@ -24,6 +24,12 @@ Capability presence is determined at mount time by which handlers you provide. U
 
 The renderer talks to a backend route you expose — the MCP client lives server-side so credentials and transport stay out of the browser. The route receives `{ method, params }` POSTs and dispatches to your MCP client.
 
+### Install the MCP client
+
+Install the AI SDK MCP client package used by the route handler:
+
+<InstallCommand npm={["@ai-sdk/mcp"]} />
+
 ### Client
 
 Compose `McpAppRenderer({...})` into your `Tools` resource. Provide `host.url` pointing at your route. Any tool-call part carrying `mcp.app` metadata renders the MCP App widget automatically.
@@ -61,19 +67,34 @@ The route accepts `POST` requests with `{ method, params }` JSON bodies. Dispatc
 
 ```ts
 // app/api/mcp-apps/route.ts
-import { experimental_createMCPClient } from "ai";
-
-let clientPromise: ReturnType<typeof experimental_createMCPClient> | undefined;
-const getClient = () => {
-  clientPromise ??= experimental_createMCPClient({
-    transport: { type: "sse", url: process.env.MCP_SERVER_URL! },
-  });
+import { createMCPClient } from "@ai-sdk/mcp";
+
+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": {
@@ -100,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 });
   }
@@ -110,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