@assistant-ui/mcp-docs-server 0.2.3 → 0.3.0

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

@@ -1,466 +0,0 @@
----
-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
-
-```mermaid
-flowchart LR
-    client["client"] --> api["/api/chat"] --> mcp["MCP client"] --> server["MCP server<br/>(HTTP, SSE, stdio)"]
-    mcp --> tools["tools()"] --> stream["passed to<br/>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`, or toolkit entries with `render`) renders the results.
-
-<Callout type="info">
-  If you use a `"use generative"` toolkit, spread `defineMcpToolkit({ ... })`
-  in the toolkit and use `AISDKToolkit` in your route. It opens the MCP clients,
-  merges their tools with your toolkit, and closes them for you.
-</Callout>
-
-## 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>
-
-### Define MCP servers in your toolkit
-
-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. Use a readable key because it appears in connection,
-tool-listing, and close errors for debugging.
-
-```tsx title="app/toolkit.tsx"
-"use generative";
-
-import { defineMcpToolkit, defineToolkit } from "@assistant-ui/react";
-
-export default defineToolkit({
-  ...defineMcpToolkit({
-    github: {
-      type: "http",
-      url: "https://mcp.example.com/mcp",
-      connectionTimeout: 10_000,
-    },
-  }),
-});
-```
-
-Use `{ server, disabled }` when a whole MCP server should stay configured but
-not expose tools for the current request, such as missing credentials, feature
-flags, or plan gating:
-
-```tsx
-defineMcpToolkit({
-  docs: {
-    server: {
-      type: "http",
-      url: process.env.DOCS_MCP_URL!,
-    },
-    disabled: !process.env.DOCS_MCP_URL,
-  },
-});
-```
-
-Use `tools` when the server should stay enabled but specific MCP tools should
-be hidden from the model:
-
-```tsx
-defineMcpToolkit({
-  docs: {
-    server: {
-      type: "http",
-      url: process.env.DOCS_MCP_URL!,
-    },
-    tools: {
-      deleteDocument: {
-        disabled: !userCanDelete,
-      },
-    },
-  },
-});
-```
-
-If multiple MCP servers expose the same tool name, wrap the entry with
-`{ server, prefix }` to give each server's tools distinct model-visible names:
-
-```tsx
-export default defineToolkit({
-  ...defineMcpToolkit({
-    docs: {
-      server: { type: "http", url: "https://docs.example.com/mcp" },
-      prefix: "docs_",
-    },
-    github: {
-      server: { type: "http", url: "https://github.example.com/mcp" },
-      prefix: "github_",
-    },
-  }),
-});
-```
-
-If both servers publish `search`, the model receives `docs_search` and
-`github_search` instead of an ambiguous duplicate.
-
-Use `AISDKToolkit` in the route. It opens the MCP clients, merges their tools
-with the rest of your toolkit, and closes them when you call `close()`:
-
-`connectionTimeout` is optional and measured in milliseconds. Set it to fail
-the server-side MCP readiness flow (`createMCPClient()` plus `tools()`) before
-a bad URL or hanging local process can stall the route.
-
-```ts title="app/api/chat/route.ts"
-import { AISDKToolkit } from "@assistant-ui/ai-sdk";
-import { openai } from "@ai-sdk/openai";
-import { streamText, convertToModelMessages } from "ai";
-import type { UIMessage } from "ai";
-import toolkit from "../../toolkit";
-
-export async function POST(req: Request) {
-  const { messages, tools }: { messages: UIMessage[]; tools?: Record<string, any> } =
-    await req.json();
-
-  const aiToolkit = new AISDKToolkit({ toolkit });
-
-  const result = streamText({
-    model: openai("gpt-5.6-luna"),
-    messages: await convertToModelMessages(messages),
-    tools: await aiToolkit.tools({ frontend: tools }),
-    onFinish: async () => {
-      await aiToolkit.close();
-    },
-  });
-
-  return result.toUIMessageStreamResponse();
-}
-```
-
-</Step>
-<Step>
-
-### Wire the tools into the route
-
-For manual MCP client control, `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.6-luna"),
-    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 in a generative
-toolkit, add an `externalTool()` renderer whose key matches the MCP tool name:
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx title="app/toolkit.tsx"
-"use generative";
-
-import { defineMcpToolkit, defineToolkit, externalTool } from "@assistant-ui/react";
-
-type Args = { repo: string; number: number };
-type Result = { title: string; state: string; url: string };
-
-export default defineToolkit({
-  ...defineMcpToolkit({
-    github: { type: "http", url: "https://mcp.example.com/mcp" },
-  }),
-  github_get_issue: {
-    execute: externalTool(),
-    render: ({ args, result }: { args: Args; result?: 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 { defineToolkit } 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 toolkit = defineToolkit({
-  github_get_issue: {
-    type: "backend",
-    render: ({ args, result }: { args: Args; result?: 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 { defineToolkit } 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 toolkit = defineToolkit({
-  github_get_issue: {
-    type: "backend",
-    render: ({ args, result }: { args: Args; result?: 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>
-
-Register the toolkit once with `Tools({ toolkit })`. Renderer keys such as
-`github_get_issue` must match the tool names your MCP server publishes.
-
-```tsx title="app/components/RuntimeProvider.tsx"
-"use client";
-
-import { AssistantRuntimeProvider, AuiConfig, Tools } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/ai-sdk";
-import type { ReactNode } from "react";
-
-import { toolkit } from "./GitHubIssueToolUI";
-
-export function MyRuntimeProvider({ children }: { children: ReactNode }) {
-  const runtime = useChatRuntime();
-  const config = AuiConfig({ tools: Tools({ toolkit }) });
-  return (
-    <AssistantRuntimeProvider
-      runtime={runtime}
-      config={config}
-    >
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-`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.6-luna"),
-  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>
-
-### 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/v7"
-  />
-  <Card
-    title="Tools and tool UI"
-    description="Build custom renderers for tool calls and approvals."
-    href="/docs/tools/defining-tools"
-  />
-</Cards>

package/.docs/raw/docs/tools/multi-agent.mdx

@@ -1,237 +0,0 @@
----
-title: Multi-Agent Chat UI
-description: Render sub-agent conversations and handoffs inside tool calls. Build supervisor and multi-agent patterns in a React chat UI with assistant-ui.
-platforms: ["react"]
----
-
-In a multi-agent (orchestrator) architecture, a main agent invokes sub-agents via tool calls. Each sub-agent may produce its own conversation (user/assistant messages, tool calls, etc.). assistant-ui supports rendering these nested conversations using the `MessagePartPrimitive.Messages` primitive.
-
-## Overview
-
-When a tool call includes a `messages` field (`ToolCallMessagePart.messages`), it represents a sub-agent's conversation history. `MessagePartPrimitive.Messages` reads this field from the current tool call part and renders it as a nested thread.
-
-Key behaviors:
-
-- **Scope inheritance** — Parent toolkit renderers are available in sub-agent messages. A `Tools({ toolkit })` registration at the top level works inside sub-agent conversations too.
-- **Recursive** — Sub-agent messages can contain tool calls that themselves have nested messages. Just use `MessagePartPrimitive.Messages` again.
-- **Read-only** — Sub-agent messages are rendered in a readonly context. No editing, branching, or composing.
-
-<Callout type="info">
-  This renders a sub-agent's **messages**. To visualize a sub-agent's **execution trace** instead (timing, span hierarchy, waterfalls), see [react-o11y](/docs/utilities/react-o11y), which renders observability spans as collapsible trees and timelines.
-</Callout>
-
-## Quick Start
-
-<Steps>
-  <Step>
-
-### Register a Tool UI for the Sub-Agent
-
-```tsx
-import {
-  defineToolkit,
-  Tools,
-  MessagePartPrimitive,
-} from "@assistant-ui/react";
-
-const toolkit = defineToolkit({
-  invoke_researcher: {
-    type: "backend",
-    render: ({ args, status }) => (
-    <div className="my-2 rounded-lg border p-4">
-      <div className="mb-2 text-sm font-medium text-gray-500">
-        Researcher Agent {status.type === "running" && "(working...)"}
-      </div>
-      <MessagePartPrimitive.Messages>
-        {({ message }) => {
-          if (message.role === "user") return <MyUserMessage />;
-          return <MyAssistantMessage />;
-        }}
-      </MessagePartPrimitive.Messages>
-    </div>
-  ),
-  },
-});
-```
-
-  </Step>
-  <Step>
-
-### Provide the Messages from the Backend
-
-Your backend must populate the `messages` field on the tool call result.
-
-<Tabs items={["AI SDK", "LangGraph"]}>
-<Tab value="AI SDK">
-
-```ts title="api/chat/route.ts"
-tools: {
-  invoke_researcher: tool({
-    description: "Invoke the researcher sub-agent",
-    parameters: z.object({ query: z.string() }),
-    execute: async ({ query }) => {
-      const subAgentMessages = await runResearcherAgent(query);
-      return {
-        answer: subAgentMessages.at(-1)?.content,
-        messages: subAgentMessages,
-      };
-    },
-  }),
-},
-```
-
-</Tab>
-<Tab value="LangGraph">
-
-With `@assistant-ui/react-langgraph`, use `unstable_createLangGraphStream` and set `unstable_allowCancellation: true` to wire up the stop button. When your graph runs a subgraph, the subgraph's messages appear on `ToolCallMessagePart.messages` automatically once you handle the `onSubgraphValues` / `onSubgraphUpdates` events.
-
-```ts title="runtime.ts"
-import {
-  useLangGraphRuntime,
-  unstable_createLangGraphStream,
-} from "@assistant-ui/react-langgraph";
-
-const runtime = useLangGraphRuntime({
-  unstable_allowCancellation: true,
-  stream: unstable_createLangGraphStream({
-    client,
-    assistantId,
-    // "custom" is required for generative UI; "updates" for subgraph events
-    streamMode: ["messages", "updates", "custom"],
-    // abort the run server-side when the user clicks stop
-    onDisconnect: "cancel",
-  }),
-  eventHandlers: {
-    onSubgraphValues: (namespace, values) => {
-      // namespace = e.g. "tools:call_abc" — the sub-agent's node path
-      // values contains the subgraph state, including its messages array
-    },
-    onSubgraphUpdates: (namespace, updates) => {
-      // incremental state updates from the subgraph
-    },
-    onSubgraphError: (namespace, error) => {
-      // error scoped to the subgraph; does not mark the parent message failed
-    },
-    onMessageChunk: (chunk, metadata) => {
-      // metadata.namespace is set when the chunk originates from a subgraph
-      // use it to attribute the chunk to the correct sub-agent
-    },
-  },
-});
-```
-
-See [LangGraph Streaming](/docs/runtimes/langgraph/streaming) for the full event handler reference.
-
-</Tab>
-</Tabs>
-
-<Callout type="info">
-  The key requirement is that the tool result's corresponding
-  `ToolCallMessagePart` includes a `messages` array of `ThreadMessage` objects.
-</Callout>
-
-  </Step>
-  <Step>
-
-### Register the Tool UI Component
-
-```tsx
-function App() {
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Thread />
-      <ResearchAgentToolUI />
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-  </Step>
-</Steps>
-
-## Subgraph Namespace Events
-
-When using LangGraph, subgraph events (`onSubgraphValues` / `onSubgraphUpdates` / `onSubgraphError`, plus the `namespace` on `onMessageChunk`) carry a `namespace` that identifies which sub-agent emitted them, letting you attribute messages and state to specific sub-agents. See [LangGraph Streaming](/docs/runtimes/langgraph/streaming) for the full reference.
-
-## Recursive Sub-Agents
-
-If a sub-agent's tool calls also have nested messages, the same pattern applies recursively:
-
-```tsx
-const toolkit = defineToolkit({
-  invoke_planner: {
-    type: "backend",
-    render: () => (
-    <div className="rounded border p-3">
-      <h4>Planner Agent</h4>
-      <MessagePartPrimitive.Messages>
-        {({ message }) => {
-          if (message.role === "user") return <MyUserMessage />;
-          return (
-            <MessagePrimitive.Parts>
-              {({ part }) => {
-                if (part.type === "text") return <MyText />;
-                if (part.type === "tool-call" && part.toolName === "invoke_researcher") return (
-                  <div className="ml-4 rounded border p-3">
-                    <h5>Researcher Agent</h5>
-                    {/* Nested sub-agent renders recursively */}
-                    <MessagePartPrimitive.Messages>
-                      {({ message }) => {
-                        if (message.role === "user") return <MyUserMessage />;
-                        return <MyAssistantMessage />;
-                      }}
-                    </MessagePartPrimitive.Messages>
-                  </div>
-                );
-                if (part.type === "tool-call") return <MyToolFallback {...part} />;
-                return null;
-              }}
-            </MessagePrimitive.Parts>
-          );
-        }}
-      </MessagePartPrimitive.Messages>
-    </div>
-  ),
-  },
-});
-```
-
-## ReadonlyThreadProvider
-
-For advanced use cases where you have a `ThreadMessage[]` array and want to render it as a thread outside of a tool call context, use `ReadonlyThreadProvider` directly:
-
-```tsx
-import {
-  ReadonlyThreadProvider,
-  ThreadPrimitive,
-  type ThreadMessage,
-} from "@assistant-ui/react";
-
-function SubConversation({
-  messages,
-}: {
-  messages: readonly ThreadMessage[];
-}) {
-  return (
-    <ReadonlyThreadProvider messages={messages}>
-      <ThreadPrimitive.Messages>
-        {({ message }) => {
-          if (message.role === "user") return <MyUserMessage />;
-          return <MyAssistantMessage />;
-        }}
-      </ThreadPrimitive.Messages>
-    </ReadonlyThreadProvider>
-  );
-}
-```
-
-`ReadonlyThreadProvider` inherits the parent's tool UI registrations and model context through scope inheritance.
-
-## Related
-
-- [Generative UI](/docs/tools/tool-ui) — Creating tool call UIs
-- [react-o11y](/docs/utilities/react-o11y) — Visualize sub-agent execution as collapsible span trees, waterfalls, and call timelines
-- [MessagePartPrimitive](/docs/api-reference/primitives/message-part) — API reference for message part primitives
-- [Sub-Agent Model Tracking](/docs/cloud/ai-sdk#sub-agent-model-tracking) — Track delegated model usage and costs in the Cloud dashboard
-- [LangGraph Streaming](/docs/runtimes/langgraph/streaming) — Event handlers, subgraph events, and message metadata
-- [LangGraph Generative UI](/docs/runtimes/langgraph/generative-ui) — Structured UI components emitted by your graph