@assistant-ui/mcp-docs-server 0.1.22 → 0.1.23

package/.docs/raw/docs/cloud/ai-sdk.mdx

@@ -0,0 +1,292 @@
+---
+title: AI SDK
+description: Add cloud persistence to your existing AI SDK app with a single hook.
+---
+
+import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
+
+## Overview
+
+The `@assistant-ui/cloud-ai-sdk` package provides a single hook that adds full message and thread persistence to any [AI SDK](https://sdk.vercel.ai/) application:
+
+- **`useCloudChat`** — wraps `useChat` with automatic cloud persistence and built-in thread management
+
+This hook works with any React UI. You keep full control of your components.
+
+<Callout type="tip">
+  See [AI SDK + assistant-ui](/docs/cloud/ai-sdk-assistant-ui) for the full integration with assistant-ui's primitives and runtime.
+</Callout>
+
+## Prerequisites
+
+<Callout type="info">
+  You need an assistant-cloud account to follow this guide. [Sign up here](https://cloud.assistant-ui.com/) to get started.
+</Callout>
+
+## Setup
+
+<Steps>
+
+<Step>
+
+### Create a Cloud Project
+
+Create a new project in the [assistant-cloud dashboard](https://cloud.assistant-ui.com/) and from the settings page, copy your **Frontend API URL** (`https://proj-[ID].assistant-api.com`).
+
+</Step>
+
+<Step>
+
+### Configure Environment Variables
+
+```bash title=".env.local"
+NEXT_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com
+```
+
+</Step>
+
+<Step>
+
+### Install Dependencies
+
+<InstallCommand npm={["@assistant-ui/cloud-ai-sdk", "assistant-cloud", "@ai-sdk/react", "ai"]} />
+
+</Step>
+
+<Step>
+
+### Integrate
+
+```tsx title="app/page.tsx"
+"use client";
+
+import { useState } from "react";
+import { useCloudChat } from "@assistant-ui/cloud-ai-sdk";
+
+export default function Chat() {
+  // Zero-config: auto-initializes anonymous cloud from env var with built-in threads.
+  // For custom config, pass: { cloud, threads: useThreads(...), onSyncError }
+  const { messages, sendMessage, threads } = useCloudChat();
+
+  const [input, setInput] = useState("");
+  const handleSubmit = () => {
+    if (!input.trim()) return;
+    sendMessage({ text: input });
+    setInput("");
+  };
+
+  return (
+    <div>
+      {/* Thread list */}
+      <ul>
+        {threads.threads.map((t) => (
+          <li key={t.id} onClick={() => threads.selectThread(t.id)}>
+            {t.title || "New conversation"}
+          </li>
+        ))}
+        <li onClick={() => threads.selectThread(null)}>New chat</li>
+      </ul>
+
+      {/* Chat messages */}
+      <div>
+        {messages.map((m) => (
+          <div key={m.id}>
+            {m.parts.map((p) => p.type === "text" && p.text)}
+          </div>
+        ))}
+      </div>
+
+      {/* Composer */}
+      <form onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
+        <input value={input} onChange={(e) => setInput(e.target.value)} />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+</Step>
+
+</Steps>
+
+That's it. Messages persist automatically as they complete, and switching threads loads the full history.
+
+## API Reference
+
+### `useCloudChat(options?)`
+
+Wraps AI SDK's `useChat` with automatic cloud persistence and built-in thread management. Messages are persisted as they finish streaming. Thread creation is automatic on the first message — the hook will auto-create the thread, select it, refresh the thread list, and generate a title after the first response.
+
+#### Configuration Modes
+
+**1. Zero-config** — Set `NEXT_PUBLIC_ASSISTANT_BASE_URL` env var, call with no args:
+
+```tsx
+const chat = useCloudChat();
+```
+
+**2. Custom cloud instance** — For authenticated users or custom configuration:
+
+```tsx
+const cloud = new AssistantCloud({ baseUrl, authToken });
+const chat = useCloudChat({ cloud });
+```
+
+**3. External thread management** — When threads need to be accessed from a separate component or you need custom thread options like `includeArchived`:
+
+```tsx
+// In a context provider or parent component
+const myThreads = useThreads({ cloud, includeArchived: true });
+
+// Pass to useCloudChat - it will use your thread state
+const chat = useCloudChat({ threads: myThreads });
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options.cloud` | `AssistantCloud` | Cloud instance (optional — auto-creates anonymous instance from `NEXT_PUBLIC_ASSISTANT_BASE_URL` env var if not provided) |
+| `options.threads` | `UseThreadsResult` | External thread management from `useThreads()`. Use when you need thread operations in a separate component or custom thread options like `includeArchived` |
+| `options.onSyncError` | `(error: Error) => void` | Callback invoked when a sync error occurs |
+
+All other [AI SDK `useChat` options](https://sdk.vercel.ai/docs/reference/ai-sdk-ui/use-chat) are also accepted.
+
+**Returns:** `UseCloudChatResult`
+
+| Value | Type | Description |
+|-------|------|-------------|
+| `messages` | `UIMessage[]` | Chat messages (from AI SDK) |
+| `status` | `string` | Chat status: `"ready"`, `"submitted"`, `"streaming"`, or `"error"` |
+| `sendMessage` | `(message, options?) => Promise<void>` | Send a message (auto-creates thread if needed) |
+| `stop` | `() => void` | Stop the current stream |
+| `threads` | `UseThreadsResult` | Thread management (see below) |
+
+Plus all other properties from AI SDK's [`UseChatHelpers`](https://sdk.vercel.ai/docs/reference/ai-sdk-ui/use-chat).
+
+**Thread management (`threads`):**
+
+| Value | Type | Description |
+|-------|------|-------------|
+| `threads.threads` | `CloudThread[]` | Active threads sorted by recency |
+| `threads.threadId` | `string \| null` | Current thread ID (`null` for a new unsaved chat) |
+| `threads.selectThread` | `(id: string \| null) => void` | Switch threads or pass `null` for a new chat |
+| `threads.isLoading` | `boolean` | `true` during initial load or refresh |
+| `threads.error` | `Error \| null` | Last error, if any |
+| `threads.refresh` | `() => Promise<boolean>` | Re-fetch the thread list |
+| `threads.delete` | `(id: string) => Promise<boolean>` | Delete a thread |
+| `threads.rename` | `(id: string, title: string) => Promise<boolean>` | Rename a thread |
+| `threads.archive` | `(id: string) => Promise<boolean>` | Archive a thread |
+| `threads.unarchive` | `(id: string) => Promise<boolean>` | Unarchive a thread |
+| `threads.generateTitle` | `(threadId: string) => Promise<string \| null>` | Generate a title using AI |
+
+### `useThreads(options)`
+
+Thread list management for use with `useCloudChat`. Call this explicitly and pass to `useCloudChat({ threads })` when you need access to thread operations outside the chat context (e.g., in a separate sidebar component).
+
+```tsx
+const myThreads = useThreads({ cloud: myCloud });
+const { messages, sendMessage } = useCloudChat({ threads: myThreads });
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options.cloud` | `AssistantCloud` | Cloud client instance |
+| `options.includeArchived` | `boolean` | Include archived threads (default: `false`) |
+| `options.enabled` | `boolean` | Enable thread fetching (default: `true`) |
+
+**Returns:** `UseThreadsResult` — same shape as `threads` from `useCloudChat()`.
+
+## Telemetry
+
+The `useCloudChat` hook automatically reports run telemetry to Assistant Cloud after each assistant response. This includes:
+
+**Automatically captured:**
+- `status` — `"completed"` or `"incomplete"` based on response content
+- `tool_calls` — Tool invocations with name, arguments, results, and source (MCP, frontend, or backend)
+- `total_steps` — Number of reasoning/tool steps in the response
+- `output_text` — Full response text (truncated at 50K characters)
+
+**Requires route configuration:**
+- `model_id` — The model used for the response
+- `input_tokens` / `output_tokens` — Token usage statistics
+
+To capture model and usage data, configure the `messageMetadata` callback in your AI SDK route:
+
+```tsx title="app/api/chat/route.ts"
+import { streamText } from "ai";
+
+export async function POST(req: Request) {
+  const result = streamText({
+    model: openai("gpt-5-mini"),
+    messages,
+  });
+
+  return result.toUIMessageStreamResponse({
+    messageMetadata: ({ part }) => {
+      if (part.type === "finish-step") {
+        return {
+          modelId: part.response.modelId,
+          usage: part.usage,
+        };
+      }
+      return undefined;
+    },
+  });
+}
+```
+
+<Callout type="info">
+  The standalone hook does not capture `duration_ms`, per-step breakdowns (`steps`), custom `metadata` pass-through, or `"error"` status. These require the full runtime integration available via [`useChatRuntime`](/docs/cloud/ai-sdk-assistant-ui).
+</Callout>
+
+### Customizing Reports
+
+Use the `beforeReport` hook to enrich or filter telemetry:
+
+```tsx
+const cloud = new AssistantCloud({
+  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+  telemetry: {
+    beforeReport: (report) => ({
+      ...report,
+      metadata: { environment: "production", version: "1.0.0" },
+    }),
+  },
+});
+```
+
+Return `null` from `beforeReport` to skip reporting a specific run. To disable telemetry entirely, pass `telemetry: false`.
+
+## Authentication
+
+The example above uses anonymous mode (browser session-based user ID) via the env var. For production apps with user accounts, pass an explicit cloud instance:
+
+```tsx
+import { useAuth } from "@clerk/nextjs";
+import { AssistantCloud } from "assistant-cloud";
+import { useCloudChat } from "@assistant-ui/cloud-ai-sdk";
+
+function Chat() {
+  const { getToken } = useAuth();
+
+  const cloud = useMemo(() => new AssistantCloud({
+    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+    authToken: async () => getToken({ template: "assistant-ui" }),
+  }), [getToken]);
+
+  const { messages, sendMessage, threads } = useCloudChat({ cloud });
+  // ...
+}
+```
+
+See the [Cloud Authorization](/docs/cloud/authorization) guide for other auth providers.
+
+## Next Steps
+
+- If you want pre-built UI components, see [AI SDK + assistant-ui](/docs/cloud/ai-sdk-assistant-ui) for the full integration
+- Learn about [user authentication](/docs/cloud/authorization) for multi-user applications
+- Check out the [complete example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud-standalone) on GitHub

package/.docs/raw/docs/cloud/authorization.mdx

@@ -3,139 +3,133 @@ title: User Authorization
 description: Configure workspace auth tokens and integrate with auth providers.
 ---
 
-The assistant-ui API can be directly accessed by your frontend. This elliminates the need for a backend server from your side, except for authorization of your users.
+The Assistant Cloud API is accessed directly from your frontend. This eliminates the need for a backend server for most operations—except for authorizing your users.
 
-This document explains how you can setup your server to authorize users to access the assistant-ui API.
+This guide explains how to set up user authentication and authorization for Assistant Cloud.
 
 ## Workspaces
 
-Authorization is granted to a workspace. Depending on the structure of your app, you might want to use user_ids as the workspace_id, or you might want to use a more complex structure.
-For example, if your app supports multiple "projects", you might want to use the project_id + user_id as the workspace id (thread history scoped to user+project pairs).
+Authorization is granted to a **workspace**. A workspace is a scope that contains threads and messages. Most commonly:
 
-## Workspace Auth Tokens
+- Use a `userId` as the workspace for personal chats
+- Use `orgId + userId` for organization-scoped conversations
+- Use `projectId + userId` for project-based apps
 
-assistant-ui issues workspace auth tokens. These tokens give access to the assistant-ui API for a specific workspace.
-Tokens are short lived (5 minutes), so the client needs to periodically request a new token (handled by assistant-ui).
+## Authentication Approaches
 
-There are two supported approaches to obtain a workspace auth token:
+Choose the approach that fits your app:
 
-- Direct integration with your auth provider
-- From a backend server / serverless function
+| Approach | Best For | Complexity |
+|----------|----------|------------|
+| **Direct auth provider integration** | Supported providers (Clerk, Auth0, Supabase, etc.) | Low |
+| **Backend server** | Custom auth, multi-user workspaces, or self-hosted solutions | Medium |
+| **Anonymous mode** | Demos, prototypes, or testing | None |
 
-### Choosing the right approach
+### Direct Integration with Auth Provider
 
-Direct integration with your auth provider:
+In the Assistant Cloud dashboard, go to **Auth Integrations** and add your provider. This sets up automatic workspace assignment based on the user's ID from your auth provider.
 
-- simpler to setup and maintain
-- assigns a workspace_id to every user (by using the user_id as the workspace_id)
-- requires a supported auth provider (Clerk, Auth0, Supabase, Firebase, Stytch, Kinde, ...)
-
-Backend server:
-
-- more complex to setup
-- more flexible workspace structure (multi-user workspaces, workspaces per project, etc.)
-- supports self hosted auth solutions, e.g. Auth.js
-- requires a backend server / serverless function
-
-You can always switch between the two approaches without any downtime or necessary database migrations.
-Choose direct integration with your auth provider if you can. Otherwise, use a backend server.
-
-### Auth Provider Integration
-In the AssistantUI dashboard, go to the "Auth Integrations" tab and add a new integration.
-Follow the steps to add your auth provider. (See the auth providers we have guides for at the bottom of this page.)
-
-Then, pass in a function to `authToken` that returns an ID token from your auth provider.
+Then pass an `authToken` function that returns your provider's ID token:
 
 ```ts
 import { AssistantCloud } from "@assistant-ui/react";
 
-const assistantCloud = new AssistantCloud({
-  authToken: () => JWT_TOKEN
+const cloud = new AssistantCloud({
+  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+  authToken: () => getTokenFromYourProvider(), // Returns JWT
 });
 ```
 
-### Integration with an Auth Provider
+### Backend Server Approach
 
-#### Backend API Endpoint
+Use this when you need custom workspace logic or unsupported auth providers.
 
-The following is an api route example to create an auth token based on an authenticated user's orgId and userId.
+<Steps>
+<Step>
 
-In the Assistant Cloud dashboard, go to the "API Keys" tab and add a new API key, add the key the environment variable `ASSISTANT_API_KEY=[KEY]`
+#### Create an API Key
+
+In the Assistant Cloud dashboard, go to **API Keys** and create a key. Add it to your environment:
+
+```bash
+ASSISTANT_API_KEY=your_key_here
+```
+
+</Step>
+<Step>
+
+#### Create the Token Endpoint
 
 ```ts title="/app/api/assistant-ui-token/route.ts"
-import { AssistantCloud } from "@assistant-ui/react";
-import { auth } from "@clerk/nextjs/server";
- 
+import { AssistantCloud } from "assistant-cloud";
+import { auth } from "@clerk/nextjs/server"; // Or your auth provider
+
 export const POST = async (req: Request) => {
   const { userId, orgId } = await auth();
- 
-  if (!userId) throw new Error("User not authenticated");
- 
+
+  if (!userId) return new Response("Unauthorized", { status: 401 });
+
+  // Define your workspace ID based on your app's structure
   const workspaceId = orgId ? `${orgId}_${userId}` : userId;
+
   const assistantCloud = new AssistantCloud({
-    apiKey: process.env["ASSISTANT_API_KEY"]!,
+    apiKey: process.env.ASSISTANT_API_KEY!,
     userId,
     workspaceId,
   });
-  const {token} = await assistantCloud.auth.tokens.create();
 
+  const { token } = await assistantCloud.auth.tokens.create();
   return new Response(token);
 };
 ```
 
-#### Frontend Implementation
+</Step>
+<Step>
 
-The following is an api route example to create an auth token based on an authenticated user's orgId and userId.
+#### Use the Token on the Frontend
 
-```ts title="client.ts"
+```tsx title="app/chat/page.tsx"
 const cloud = new AssistantCloud({
-  baseUrl: process.env["NEXT_PUBLIC_ASSISTANT_BASE_URL"]!,
+  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
   authToken: () =>
-    fetch("/api/assistant-ui-token", { method: "POST" }).then((r) =>
-      r.text(),
-    ),
+    fetch("/api/assistant-ui-token", { method: "POST" }).then((r) => r.text()),
 });
 
 const runtime = useChatRuntime({
-  api: "/api/chat",
   cloud,
 });
 ```
 
-### Anonymous (without auth provider) Frontend Implementation
+</Step>
+</Steps>
 
-The following is a example to get auth tokens for Clerk based on the org_id and user_id:
+### Anonymous Mode (No Auth)
 
-```ts title="/app/api/assistant-ui-token/route.ts"
+For demos or testing, use anonymous mode to create browser-session-based users:
+
+```tsx
 import { AssistantCloud } from "@assistant-ui/react";
 
 const cloud = new AssistantCloud({
-  baseUrl: process.env["NEXT_PUBLIC_ASSISTANT_BASE_URL"]!,
+  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
   anonymous: true,
 });
+```
 
-const runtime = useChatRuntime({
-  api: "/api/chat",
-  cloud,
-});
-
-return (
-  <AssistantRuntimeProvider runtime={runtime}>
-    <div className="grid h-dvh grid-cols-[200px_1fr] gap-x-2 px-4 py-4">
-      <ThreadList />
-      <MyThread />
-    </div>
-  </AssistantRuntimeProvider>
-);
+<Callout type="warning">
+  Anonymous mode creates a new user for each browser session. Threads won't persist across sessions or devices. Use this only for prototyping.
+</Callout>
 
-```
+## Auth Provider Examples
 
+### Clerk
 
-### Setting up the Clerk Auth Provider
+<Steps>
+<Step>
 
-First, go to the Clerk dashboard and under "Configure" tab, "JWT Templates" section, create a new template. Choose a blank template and name it "assistant-ui".
+#### Configure the JWT Template
 
-As the "Claims" field, enter the following:
+In the Clerk dashboard, go to **Configure → JWT Templates**. Create a new blank template named "assistant-ui":
 
 ```json
 {
@@ -143,11 +137,116 @@ As the "Claims" field, enter the following:
 }
 ```
 
-<Callout emoji="⚠️">
-  <b>Note:</b> The aud claim ensures that the JWT is only valid for the
-  assistant-ui API.
+<Callout type="info">
+  The `aud` claim ensures the JWT is only valid for Assistant Cloud.
 </Callout>
 
-You can leave everything else as default. Take note of the "Issuer" and "JWKS Endpoint" fields.
+Note the **Issuer** and **JWKS Endpoint** values.
+
+</Step>
+<Step>
+
+#### Add Auth Integration in Assistant Cloud
+
+In the Assistant Cloud dashboard, go to **Auth Rules** and create a new rule:
+
+- **Provider**: Clerk
+- **Issuer**: Paste from Clerk JWT Template
+- **JWKS Endpoint**: Paste from Clerk JWT Template
+- **Audience**: `assistant-ui`
+
+</Step>
+<Step>
 
-Then, In the assistant-cloud dashboard, navigate to the "Auth Rules" tab and create a new rule. Choose "Clerk" and enter the Issuer and JWKS Endpoint from the previous step. As the "Audience" field, enter "assistant-ui".
+#### Use in Your App
+
+```tsx
+import { useAuth } from "@clerk/nextjs";
+import { AssistantCloud } from "@assistant-ui/react";
+
+function Chat() {
+  const { getToken } = useAuth();
+
+  const cloud = useMemo(
+    () =>
+      new AssistantCloud({
+        baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+        authToken: () => getToken({ template: "assistant-ui" }),
+      }),
+    [getToken],
+  );
+
+  // Use with your runtime...
+}
+```
+
+</Step>
+</Steps>
+
+### Auth0
+
+```tsx
+import { useAuth0 } from "@auth0/auth0-react";
+import { AssistantCloud } from "@assistant-ui/react";
+
+function Chat() {
+  const { getAccessTokenSilently } = useAuth0();
+
+  const cloud = useMemo(
+    () =>
+      new AssistantCloud({
+        baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+        authToken: () => getAccessTokenSilently(),
+      }),
+    [getAccessTokenSilently],
+  );
+
+  // Use with your runtime...
+}
+```
+
+Configure the Auth0 integration in the Assistant Cloud dashboard with your Auth0 domain and audience.
+
+### Supabase Auth
+
+```tsx
+import { useSupabaseClient } from "@supabase/auth-helpers-react";
+import { AssistantCloud } from "@assistant-ui/react";
+
+function Chat() {
+  const supabase = useSupabaseClient();
+
+  const cloud = useMemo(
+    () =>
+      new AssistantCloud({
+        baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+        authToken: async () => {
+          const { data } = await supabase.auth.getSession();
+          return data.session?.access_token ?? "";
+        },
+      }),
+    [supabase],
+  );
+
+  // Use with your runtime...
+}
+```
+
+### Firebase Auth
+
+```tsx
+import { getAuth, getIdToken } from "firebase/auth";
+import { AssistantCloud } from "@assistant-ui/react";
+
+function Chat() {
+  const cloud = useMemo(() => {
+    const auth = getAuth();
+    return new AssistantCloud({
+      baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+      authToken: () => getIdToken(auth.currentUser!, true),
+    });
+  }, []);
+
+  // Use with your runtime...
+}
+```

package/.docs/raw/docs/cloud/{persistence/langgraph.mdx → langgraph.mdx}

@@ -1,12 +1,12 @@
 ---
-title: Chat History for LangGraph Cloud
+title: LangGraph + assistant-ui
 description: Integrate cloud persistence and thread management with LangGraph Cloud.
 ---
 
 
 ## Overview
 
-assistant-cloud provides thread management and persistent chat history for applications built with [LangGraph Cloud](https://langchain-ai.github.io/langgraph/cloud/). This guide shows you how to integrate cloud persistence into your LangGraph application.
+This guide shows how to integrate Assistant Cloud with [LangGraph Cloud](https://langchain-ai.github.io/langgraph/cloud/) using assistant-ui's runtime system and pre-built UI components.
 
 ## Prerequisites