@assistant-ui/mcp-docs-server 0.1.29 → 0.1.31

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

@@ -0,0 +1,267 @@
+---
+title: Model Context Protocol (MCP)
+description: Connect MCP servers as a tool catalog in your assistant-ui app.
+---
+
+[MCP](https://modelcontextprotocol.io/) is an open protocol for exposing tools, resources, and prompts to LLMs. One MCP server can publish many tools (file system, GitHub, Slack, your own service) and any MCP-aware client can use them. The AI SDK has a built-in MCP client; this page is the wiring guide for plugging it into an assistant-ui app.
+
+## How it works
+
+```
+client  ──►  /api/chat  ──►  MCP client  ──►  MCP server (HTTP, SSE, stdio)
+                            │
+                            └─ tools()  ──►  passed to streamText({ tools })
+```
+
+The MCP client lives on the server inside your AI SDK route handler. It connects to one or more MCP servers, calls `tools()` to get a tool map, and hands that map to `streamText`. assistant-ui's existing tool-call UI (`ToolFallback`, `makeAssistantToolUI`) renders the results.
+
+## Setup
+
+<Steps>
+<Step>
+
+### Install the MCP client
+
+<InstallCommand npm={["@ai-sdk/mcp"]} />
+
+For stdio transports (local dev only), also install the official MCP SDK:
+
+<InstallCommand npm={["@modelcontextprotocol/sdk"]} />
+
+</Step>
+<Step>
+
+### Connect to an MCP server
+
+Set the server URL and any auth token your server requires:
+
+```sh title=".env.local"
+MCP_SERVER_URL=https://your-mcp-server.example/mcp
+MCP_TOKEN=...
+```
+
+Then inside your AI SDK route handler, create the client with the transport that matches your server. **HTTP** is the production transport; **SSE** is the legacy streaming transport; **stdio** spawns a local process and is dev-only.
+
+```ts title="app/api/chat/route.ts"
+import { createMCPClient } from "@ai-sdk/mcp";
+
+const mcpClient = await createMCPClient({
+  transport: {
+    type: "http",
+    url: process.env.MCP_SERVER_URL!,
+    headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` },
+  },
+});
+```
+
+For stdio:
+
+```ts
+import { createMCPClient } from "@ai-sdk/mcp";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const mcpClient = await createMCPClient({
+  transport: new StdioClientTransport({
+    command: "node",
+    args: ["./mcp-server/dist/index.js"],
+  }),
+});
+```
+
+</Step>
+<Step>
+
+### Wire the tools into the route
+
+`mcpClient.tools()` returns an object shaped exactly like the `tools` argument of `streamText`. Spread it in alongside any of your own tools, and close the client when the response finishes:
+
+```ts title="app/api/chat/route.ts"
+import { createMCPClient } from "@ai-sdk/mcp";
+import { openai } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages } from "ai";
+import type { UIMessage } from "ai";
+
+export const maxDuration = 60;
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+
+  const mcpClient = await createMCPClient({
+    transport: {
+      type: "http",
+      url: process.env.MCP_SERVER_URL!,
+      headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` },
+    },
+  });
+
+  const tools = await mcpClient.tools();
+
+  const result = streamText({
+    model: openai("gpt-5.4-mini"),
+    messages: await convertToModelMessages(messages),
+    tools,
+    onFinish: async () => {
+      await mcpClient.close();
+    },
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+`onFinish` is the right place to call `close()`: it fires after the stream completes, so the connection stays open as long as the model is still calling tools.
+
+</Step>
+<Step>
+
+### Combine multiple MCP servers
+
+Each server has its own client. Spread their tool maps together:
+
+```ts
+const githubClient = await createMCPClient({
+  transport: { type: "http", url: process.env.GITHUB_MCP_URL! },
+});
+const filesClient = await createMCPClient({
+  transport: { type: "http", url: process.env.FILES_MCP_URL! },
+});
+
+const tools = {
+  ...(await githubClient.tools()),
+  ...(await filesClient.tools()),
+};
+
+// remember to close both in onFinish
+```
+
+If two servers expose tools with the same name, the later spread wins. Rename or scope as needed.
+
+</Step>
+<Step>
+
+### Render results in the UI
+
+Tool calls flow through the existing assistant-ui tool-call rendering. With no setup, the bundled `<ToolFallback>` component renders the call name, arguments, and result. To customize the appearance for a specific tool, use `makeAssistantToolUI`:
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx title="app/components/GitHubIssueToolUI.tsx"
+"use client";
+
+import { makeAssistantToolUI } from "@assistant-ui/react";
+
+type Args = { repo: string; number: number };
+type Result = { title: string; state: string; url: string };
+
+export const GitHubIssueToolUI = makeAssistantToolUI<Args, Result>({
+  toolName: "github_get_issue",
+  render: ({ args, result }) => (
+    <div className="rounded border p-3">
+      <div className="font-mono text-sm">{args.repo}#{args.number}</div>
+      {result && (
+        <a href={result.url} className="underline">
+          {result.title} ({result.state})
+        </a>
+      )}
+    </div>
+  ),
+});
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx title="components/GitHubIssueToolUI.tsx"
+import { makeAssistantToolUI } from "@assistant-ui/react-native";
+import { Linking, Pressable, Text, View } from "react-native";
+
+type Args = { repo: string; number: number };
+type Result = { title: string; state: string; url: string };
+
+export const GitHubIssueToolUI = makeAssistantToolUI<Args, Result>({
+  toolName: "github_get_issue",
+  render: ({ args, result }) => (
+    <View style={{ borderWidth: 1, borderRadius: 6, padding: 12 }}>
+      <Text style={{ fontFamily: "Menlo", fontSize: 13 }}>
+        {args.repo}#{args.number}
+      </Text>
+      {result && (
+        <Pressable onPress={() => Linking.openURL(result.url)}>
+          <Text style={{ textDecorationLine: "underline" }}>
+            {result.title} ({result.state})
+          </Text>
+        </Pressable>
+      )}
+    </View>
+  ),
+});
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="components/GitHubIssueToolUI.tsx"
+import { makeAssistantToolUI } from "@assistant-ui/react-ink";
+import { Box, Text } from "ink";
+
+type Args = { repo: string; number: number };
+type Result = { title: string; state: string; url: string };
+
+export const GitHubIssueToolUI = makeAssistantToolUI<Args, Result>({
+  toolName: "github_get_issue",
+  render: ({ args, result }) => (
+    <Box borderStyle="round" paddingX={1} flexDirection="column">
+      <Text>
+        {args.repo}#{args.number}
+      </Text>
+      {result && (
+        <Text>
+          {result.title} ({result.state}) — {result.url}
+        </Text>
+      )}
+    </Box>
+  ),
+});
+```
+
+</Tab>
+</PlatformTabs>
+
+Mount it once anywhere inside `<AssistantRuntimeProvider>`. The `toolName` must match the name your MCP server publishes.
+
+</Step>
+<Step>
+
+### Run and verify
+
+Start the app and trigger a tool call (e.g., ask the assistant to do something the MCP server can do). Confirm:
+
+- The tool call appears in the chat with the expected arguments.
+- The result renders (either via your custom `ToolUI` or the fallback).
+- No connection leaks: the MCP client closes after each response. If you see open connections accumulating, check `onFinish`.
+
+</Step>
+</Steps>
+
+## Notes
+
+- **Server-side only.** The MCP client uses Node APIs (sockets, optionally child processes). Never instantiate it in client code.
+- **Per-request lifecycle.** A fresh client per request keeps connection state simple. For high-throughput servers, pool clients yourself with care: the AI SDK's `tools()` call assumes the connection is alive when `streamText` runs.
+- **Sampling.** If your MCP server uses `sampling/createMessage` (lets the server ask the LLM mid-call), assistant-cloud users can instrument it via [`instrumentMcpSampling`](/docs/cloud) for observability. This is independent of the wiring above.
+- **Transport choice.** HTTP for any networked server. SSE only if the server doesn't speak HTTP. stdio is for local development against an MCP server in your monorepo.
+
+## Related
+
+<Cards>
+  <Card
+    title="AI SDK runtime"
+    description="The runtime that ferries MCP tool calls to the chat UI."
+    href="/docs/runtimes/ai-sdk/v6"
+  />
+  <Card
+    title="Tools and tool UI"
+    description="Build custom renderers for tool calls and approvals."
+    href="/docs/guides/tools"
+  />
+</Cards>

package/.docs/raw/docs/primitives/action-bar.mdx

@@ -1,6 +1,7 @@
 ---
 title: ActionBar
 description: Build message action buttons with auto-hide, copy state, and intelligent disabling.
+platforms: ["react"]
 ---
 
 import { ActionBarPrimitiveSample } from "@/components/docs/samples/action-bar-primitive";

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

@@ -1,6 +1,7 @@
 ---
 title: AssistantModal
 description: A floating chat popover with a fixed-position trigger button that opens a chat panel.
+platforms: ["react"]
 ---
 
 import { AssistantModalSample } from "@/components/docs/samples/assistant-modal";

package/.docs/raw/docs/primitives/attachment.mdx

@@ -1,6 +1,7 @@
 ---
 title: Attachment
 description: File and image attachment rendering for the composer and messages.
+platforms: ["react"]
 ---
 
 import { AttachmentSample } from "@/components/docs/samples/attachment";

package/.docs/raw/docs/primitives/branch-picker.mdx

@@ -1,6 +1,7 @@
 ---
 title: BranchPicker
 description: Navigate between message branches, which are alternative responses the user can flip through.
+platforms: ["react"]
 ---
 
 import { BranchPickerPrimitiveSample } from "@/components/docs/samples/branch-picker-primitive";

package/.docs/raw/docs/primitives/chain-of-thought.mdx

@@ -1,15 +1,19 @@
 ---
 title: ChainOfThought
 description: Collapsible accordion for grouping reasoning steps and tool calls.
+platforms: ["react"]
 ---
 
 import { ChainOfThoughtPrimitiveSample } from "@/components/docs/samples/chain-of-thought-primitive";
-import { ChainOfThoughtPrimitive as ChainOfThoughtPrimitiveDocs } from "@/generated/primitiveDocs";
+import {
+  ChainOfThoughtPrimitive as ChainOfThoughtPrimitiveDocs,
+  MessagePrimitive as MessagePrimitiveDocs,
+} from "@/generated/primitiveDocs";
 
-The ChainOfThought primitive groups consecutive reasoning and tool-call parts into a collapsible accordion. Reasoning models emit reasoning tokens and tool calls before producing a final answer. This primitive lets you collapse those intermediate steps behind a "Thinking" toggle.
+The ChainOfThought primitive is the legacy accordion API for grouped reasoning and tool-call parts. Reasoning models emit reasoning tokens and tool calls before producing a final answer.
 
-<Callout type="info">
-Grouped Chain of Thought currently plugs into `MessagePrimitive.Parts` via `components.ChainOfThought`. If you're wiring grouped CoT, use that API.
+<Callout type="warn">
+For new grouped reasoning/tool-call UI, use `MessagePrimitive.GroupedParts`. `ChainOfThoughtPrimitive` and `components.ChainOfThought` remain available for maintaining existing code.
 </Callout>
 
 <Tabs items={["Preview", "Code"]}>
@@ -18,105 +22,106 @@ Grouped Chain of Thought currently plugs into `MessagePrimitive.Parts` via `comp
   </Tab>
   <Tab>
 ```tsx
-import {
-  AuiIf,
-  ChainOfThoughtPrimitive,
-  MessagePrimitive,
-} from "@assistant-ui/react";
+import { MessagePrimitive } from "@assistant-ui/react";
 
 function AssistantMessage() {
   return (
     <MessagePrimitive.Root>
-      <MessagePrimitive.Parts>
-        {({ part }) => {
-          if (part.type === "text") return <MyText />;
+      <MessagePrimitive.GroupedParts
+        groupBy={(part) => {
+          if (part.type === "reasoning")
+            return ["group-chainOfThought", "group-reasoning"];
+          if (part.type === "tool-call")
+            return ["group-chainOfThought", "group-tool"];
           return null;
         }}
-      </MessagePrimitive.Parts>
-      <ChainOfThought />
+      >
+        {({ part, children }) => {
+          switch (part.type) {
+            case "group-chainOfThought":
+              return <ThinkingAccordion>{children}</ThinkingAccordion>;
+            case "group-reasoning":
+              return <ReasoningGroup>{children}</ReasoningGroup>;
+            case "group-tool":
+              return <ToolGroup>{children}</ToolGroup>;
+            case "text":
+              return <MyText />;
+            case "reasoning":
+              return <MyReasoning {...part} />;
+            case "tool-call":
+              return part.toolUI ?? <MyToolFallback {...part} />;
+            default:
+              return null;
+          }
+        }}
+      </MessagePrimitive.GroupedParts>
     </MessagePrimitive.Root>
   );
 }
-
-function ChainOfThought() {
-  return (
-    <ChainOfThoughtPrimitive.Root className="my-2 rounded-lg border">
-      <ChainOfThoughtPrimitive.AccordionTrigger className="flex w-full cursor-pointer items-center gap-2 px-4 py-2.5 font-medium text-sm hover:bg-muted/50">
-        Thinking
-      </ChainOfThoughtPrimitive.AccordionTrigger>
-      <AuiIf condition={(s) => !s.chainOfThought.collapsed}>
-        <ChainOfThoughtPrimitive.Parts
-          components={{
-            Reasoning: ({ text }) => (
-              <p className="whitespace-pre-wrap px-4 py-2 text-muted-foreground text-sm italic">
-                {text}
-              </p>
-            ),
-            tools: {
-              Fallback: ({ toolName, status }) => (
-                <div className="flex items-center gap-2 px-4 py-2 text-sm">
-                  <span className="font-medium">{toolName}</span>
-                  <span className="text-muted-foreground">
-                    {status.type === "running" ? "running..." : "done"}
-                  </span>
-                </div>
-              ),
-            },
-          }}
-        />
-      </AuiIf>
-    </ChainOfThoughtPrimitive.Root>
-  );
-}
 ```
   </Tab>
 </Tabs>
 
-## Quick Start
+## Recommended: GroupedParts
 
-Render your normal message parts with `MessagePrimitive.Parts`, then place a `ChainOfThought` component alongside them inside the same `MessagePrimitive.Root`:
+Group reasoning and tool-call parts directly in your assistant message:
 
 ```tsx
-import {
-  ChainOfThoughtPrimitive,
-  MessagePrimitive,
-} from "@assistant-ui/react";
+import { MessagePrimitive } from "@assistant-ui/react";
 
 <MessagePrimitive.Root>
-  <MessagePrimitive.Parts>
-    {({ part }) => {
-      if (part.type === "text") return <MyText />;
+  <MessagePrimitive.GroupedParts
+    groupBy={(part) => {
+      if (part.type === "reasoning")
+        return ["group-chainOfThought", "group-reasoning"];
+      if (part.type === "tool-call")
+        return ["group-chainOfThought", "group-tool"];
       return null;
     }}
-  </MessagePrimitive.Parts>
-  <MyChainOfThought />
+  >
+    {({ part, children }) => {
+      switch (part.type) {
+        case "group-chainOfThought":
+          return <ThinkingAccordion>{children}</ThinkingAccordion>;
+        case "group-reasoning":
+          return <ReasoningGroup>{children}</ReasoningGroup>;
+        case "group-tool":
+          return <ToolGroup>{children}</ToolGroup>;
+        case "text":
+          return <MyText />;
+        case "reasoning":
+          return <MyReasoning {...part} />;
+        case "tool-call":
+          return part.toolUI ?? <MyToolFallback {...part} />;
+        default:
+          return null;
+      }
+    }}
+  </MessagePrimitive.GroupedParts>
 </MessagePrimitive.Root>
-
-function MyChainOfThought() {
-  return (
-    <ChainOfThoughtPrimitive.Root>
-      <ChainOfThoughtPrimitive.AccordionTrigger>
-        Thinking
-      </ChainOfThoughtPrimitive.AccordionTrigger>
-      <ChainOfThoughtPrimitive.Parts />
-    </ChainOfThoughtPrimitive.Root>
-  );
-}
 ```
 
-`Root` renders a `<div>`, `AccordionTrigger` renders a `<button>` that toggles the collapsed state, and `Parts` renders the grouped reasoning and tool-call parts.
+### GroupedParts API Reference
+
+<PrimitivesTypeTable type="MessagePrimitiveGroupedPartsProps" parameters={MessagePrimitiveDocs.GroupedParts.props} />
+
+## Legacy: ChainOfThoughtPrimitive
+
+### Quick Start
+
+Render your normal message parts with `MessagePrimitive.Parts`, then place a `ChainOfThought` component alongside them inside the same `MessagePrimitive.Root` only when maintaining older code that already uses the ChainOfThought primitive.
 
 <Callout type="info">
 Runtime setup: primitives require runtime context. Wrap your UI in `AssistantRuntimeProvider` with a runtime (for example `useLocalRuntime(...)`). See [Pick a Runtime](/docs/runtimes/pick-a-runtime).
 </Callout>
 
-## Core Concepts
+### Concepts
 
-### How Grouping Works
+#### How Grouping Works
 
-`ChainOfThoughtPrimitive.Parts` reads the current message's grouped reasoning and tool-call context. In practice, render your normal text/image/data parts with `MessagePrimitive.Parts`, and render `ChainOfThoughtPrimitive` separately where you want the collapsible reasoning block to appear.
+`ChainOfThoughtPrimitive.Parts` reads the current message's grouped reasoning and tool-call context from the legacy `components.ChainOfThought` path. New code should use `MessagePrimitive.GroupedParts` instead.
 
-### Collapsed State
+#### Collapsed State
 
 The accordion starts collapsed by default. `AccordionTrigger` toggles between collapsed and expanded. Use `AuiIf` to conditionally render parts based on the collapsed state:
 
@@ -135,7 +140,7 @@ import { AuiIf, ChainOfThoughtPrimitive } from "@assistant-ui/react";
 </ChainOfThoughtPrimitive.Root>
 ```
 
-### Chevron Indicators
+#### Chevron Indicators
 
 Use `AuiIf` to show directional icons that reflect the current state:
 
@@ -154,9 +159,9 @@ import { ChevronDownIcon, ChevronRightIcon } from "lucide-react";
 </ChainOfThoughtPrimitive.AccordionTrigger>
 ```
 
-### Parts Components
+#### Parts Components
 
-`ChainOfThoughtPrimitive.Parts` accepts a `components` prop to control how each part type renders:
+`ChainOfThoughtPrimitive.Parts` accepts a deprecated `components` prop to control how each part type renders:
 
 ```tsx
 <ChainOfThoughtPrimitive.Parts
@@ -186,9 +191,9 @@ import { ChevronDownIcon, ChevronRightIcon } from "lucide-react";
 | `components.tools.Fallback` | `ToolCallMessagePartComponent` | Fallback for tool-call parts |
 | `components.Layout` | `ComponentType<PropsWithChildren>` | Wrapper around each rendered part |
 
-## Parts
+### Parts API Reference
 
-### Root
+#### Root
 
 Container for the chain-of-thought disclosure UI. Renders a `<div>` element unless `asChild` is set.
 
@@ -198,7 +203,7 @@ Container for the chain-of-thought disclosure UI. Renders a `<div>` element unle
 </ChainOfThoughtPrimitive.Root>
 ```
 
-### AccordionTrigger
+#### AccordionTrigger
 
 Trigger that toggles the collapsed state. Renders a `<button>` element unless `asChild` is set.
 
@@ -208,7 +213,7 @@ Trigger that toggles the collapsed state. Renders a `<button>` element unless `a
 </ChainOfThoughtPrimitive.AccordionTrigger>
 ```
 
-### Parts
+#### Parts
 
 Renders reasoning and tool-call parts. This component does not track collapsed state internally, so control visibility with `AuiIf` as shown in the patterns below.
 
@@ -233,9 +238,9 @@ Renders reasoning and tool-call parts. This component does not track collapsed s
 
 <PrimitivesTypeTable type="ChainOfThoughtPrimitivePartsProps" parameters={ChainOfThoughtPrimitiveDocs.Parts.props} />
 
-## Patterns
+### Patterns
 
-### Minimal Accordion
+#### Minimal Accordion
 
 ```tsx
 function ChainOfThought() {
@@ -260,7 +265,7 @@ function ChainOfThought() {
 }
 ```
 
-### With Tool Calls
+#### With Tool Calls
 
 ```tsx
 function ChainOfThought() {
@@ -298,11 +303,11 @@ function ChainOfThought() {
 }
 ```
 
-## Relationship to Components
+### Relationship to Components
 
-The [Chain of Thought guide](/docs/guides/chain-of-thought) covers end-to-end setup including backend configuration with reasoning models. See the complete [with-chain-of-thought example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-chain-of-thought) for a full working implementation.
+The [Chain of Thought guide](/docs/guides/chain-of-thought) covers end-to-end setup with `MessagePrimitive.GroupedParts`, including backend configuration with reasoning models. See the complete [with-chain-of-thought example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-chain-of-thought) for a full working implementation.
 
-## API Reference
+### API Reference
 
 For the complete guide including backend configuration, see [Chain of Thought](/docs/guides/chain-of-thought). For prop details, see the [ChainOfThoughtPrimitive source](https://github.com/assistant-ui/assistant-ui/tree/main/packages/react/src/primitives/chainOfThought).