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

package/.docs/raw/docs/integrations/index.mdx

@@ -0,0 +1,173 @@
+---
+title: Integrations
+description: Third-party services and adapter recipes that plug into a working assistant-ui app.
+---
+
+import { MastraIcon } from "@/components/icons/mastra";
+import { VercelIcon } from "@/components/icons/vercel";
+import { LangChainIcon } from "@/components/icons/langchain";
+
+Integrations are wiring guides for using third-party services with assistant-ui, plus canonical recipes for the adapter slots (persistence, attachments). They are distinct from [runtimes](/docs/runtimes/pick-a-runtime), which are the React adapter packages (`@assistant-ui/react-ai-sdk`, `@assistant-ui/react-langgraph`, etc.) that connect the UI to a backend. An integration assumes you already have a working runtime and adds something on top.
+
+## Where integrations slot in
+
+```
+client  ──►  your API route  ──►  LLM provider
+                │                    ▲
+                │                    │
+     agent      │                    │  observability
+     frameworks │                    │  proxies
+     (e.g.      │                    │  (e.g. Helicone,
+     Mastra)    │                    │   Langfuse)
+                ▼                    │
+          run on the server,         │
+          then forward calls   ──────┘
+          to the provider
+```
+
+Integrations live on the server. **Agent frameworks** like Mastra take over the API route. **Gateways** swap the upstream provider URL. **Observability** logs or traces every call. **Auth** gates the route and scopes per-user data. **Persistence** and **attachments** are adapter recipes for storing chat data outside the default in-memory path.
+
+## Frameworks
+
+Framework integrations that pair with assistant-ui at the API-route layer.
+
+<Cards>
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="Vercel AI SDK"
+    description="The canonical first-party adapter. Full setup lives under runtimes; this entry is the architectural pointer."
+    href="/docs/integrations/frameworks/ai-sdk"
+  />
+  <PlatformOnly platforms={["react"]}>
+    <Card
+      icon={<MastraIcon width={20} height={20} />}
+      title="Mastra"
+      description="TypeScript agent framework. Routed through the AI SDK runtime, full-stack or separate server."
+      href="/docs/integrations/frameworks/mastra/overview"
+    />
+  </PlatformOnly>
+</Cards>
+
+## Tools
+
+Pluggable tool catalogs and protocols.
+
+<Cards>
+  <Card
+    title="Model Context Protocol (MCP)"
+    description="Connect any MCP server as a tool catalog through the AI SDK MCP client."
+    href="/docs/integrations/tools/mcp"
+  />
+</Cards>
+
+## Gateways
+
+OpenAI-compatible proxies that add catalog routing, fallback, BYOK, or self-hosting.
+
+<Cards>
+  <Card
+    title="LLM gateways"
+    description="OpenRouter, Portkey, LiteLLM Proxy. Swap baseURL, route across providers."
+    href="/docs/integrations/gateways"
+  />
+</Cards>
+
+## Observability
+
+Log, monitor, trace, and evaluate LLM calls. These pair with any runtime.
+
+<Cards>
+  <Card
+    title="Helicone"
+    description="Observability proxy. Drop-in baseURL swap that logs cost, latency, and prompts."
+    href="/docs/integrations/observability/helicone"
+  />
+  <Card
+    icon={<LangChainIcon width={20} height={20} className="text-[#7FC8FF]" />}
+    title="Langfuse"
+    description="OpenTelemetry-based tracing and evals. Open source, self-hostable."
+    href="/docs/integrations/observability/langfuse"
+  />
+  <Card
+    icon={<LangChainIcon width={20} height={20} className="text-[#7FC8FF]" />}
+    title="LangSmith"
+    description="LangChain ecosystem tracing via wrapAISDK. Datasets and evals included."
+    href="/docs/integrations/observability/langsmith"
+  />
+</Cards>
+
+<PlatformOnly platforms={["react"]}>
+
+## Auth
+
+Gate the chat route and scope thread data to the signed-in user. These pages are the **non-cloud** path; pair with [custom thread persistence](/docs/integrations/persistence/custom-adapter) when you own the database.
+
+<Cards>
+  <Card
+    title="Clerk"
+    description="Hosted auth with a Next.js middleware. auth() returns userId; Clerk Orgs map to multi-tenant chat."
+    href="/docs/integrations/auth/clerk"
+  />
+  <Card
+    title="better-auth"
+    description="TypeScript-first, owns the user table and session. session.user.id is populated by default."
+    href="/docs/integrations/auth/better-auth"
+  />
+  <Card
+    title="Auth.js (next-auth)"
+    description="The OSS Next.js standard. Requires jwt/session callbacks to populate session.user.id."
+    href="/docs/integrations/auth/next-auth"
+  />
+</Cards>
+
+For AssistantCloud users, [cloud authorization](/docs/cloud/authorization) handles the JWT exchange for Clerk, Auth0, Supabase, and Firebase without DB code.
+
+</PlatformOnly>
+
+## Persistence
+
+Store threads and messages outside AssistantCloud.
+
+<Cards>
+  <Card
+    title="Custom thread persistence"
+    description="Worked example: Postgres + Drizzle, RemoteThreadListAdapter, ThreadHistoryAdapter with withFormat."
+    href="/docs/integrations/persistence/custom-adapter"
+  />
+</Cards>
+
+## Attachments
+
+Upload chat attachments to object storage instead of inlining as data URLs.
+
+<Cards>
+  <Card
+    title="Custom attachment uploads"
+    description="Production AttachmentAdapter with presigned URLs. Tabs for S3/R2, Vercel Blob, Uploadthing."
+    href="/docs/integrations/attachments/custom-adapter"
+  />
+</Cards>
+
+## Don't see your service?
+
+assistant-ui doesn't ship a guide for every tool, but most fit one of two patterns:
+
+- **Routes through your AI SDK handler** (agent frameworks, observability proxies, gateways): adapt the [Mastra full-stack](/docs/integrations/frameworks/mastra/full-stack) or [Helicone proxy](/docs/integrations/observability/helicone) pattern using the service's own SDK.
+- **Replaces the runtime entirely** (custom backends): see [custom backend](/docs/runtimes/custom).
+
+If you build something useful, [open an issue](https://github.com/assistant-ui/assistant-ui/issues) or post in [Discord](https://discord.gg/S9dwgCNEFs); the docs are open to contributions.
+
+## Related
+
+<Cards>
+  <Card
+    title="Pick a runtime"
+    description="Choose the React adapter that matches your backend before adding integrations."
+    href="/docs/runtimes/pick-a-runtime"
+  />
+  <Card
+    title="Runtime concepts"
+    description="Architecture, adapters, threads, and stability across all runtimes."
+    href="/docs/runtimes/concepts/architecture"
+  />
+</Cards>

package/.docs/raw/docs/integrations/observability/helicone.mdx

@@ -0,0 +1,130 @@
+---
+title: Helicone
+description: Log and monitor LLM calls by routing them through the Helicone proxy.
+---
+
+import { VercelIcon } from "@/components/icons/vercel";
+
+[Helicone](https://www.helicone.ai/) is an LLM observability proxy. Point your provider client at Helicone's URL, add an auth header, and every request and response is recorded with cost, latency, and prompt-level diffs.
+
+Helicone is independent of which assistant-ui runtime you use. It slots in at the LLM-client layer (OpenAI SDK, AI SDK provider, or any HTTP-based provider client) on the server, not at the assistant-ui client runtime layer. So it pairs with any backend: AI SDK, LangGraph, Mastra, custom.
+
+## How it works
+
+```
+your server  ──►  Helicone proxy  ──►  OpenAI / Anthropic / etc.
+                  │
+                  └─ logs request, response, tokens, cost
+```
+
+Calls pass through Helicone's edge before reaching the upstream provider. The proxy is transparent: response shape and streaming behavior are unchanged, you just gain a dashboard of every call.
+
+## Setup
+
+<Steps>
+<Step>
+
+### Get a Helicone API key
+
+Sign up at [helicone.ai](https://www.helicone.ai/) and copy the key from the dashboard. Add it to your environment alongside the provider key:
+
+```sh title=".env.local"
+HELICONE_API_KEY=sk-helicone-...
+OPENAI_API_KEY=sk-...
+```
+
+</Step>
+<Step>
+
+### Point the provider client at the proxy
+
+Swap the provider's `baseURL` for Helicone's proxy URL and add the `Helicone-Auth` header.
+
+<Tabs items={["AI SDK", "OpenAI SDK"]}>
+<Tab value="AI SDK">
+
+```ts title="app/api/chat/route.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages } from "ai";
+import type { UIMessage } from "ai";
+
+const openai = createOpenAI({
+  baseURL: "https://oai.helicone.ai/v1",
+  headers: {
+    "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`,
+  },
+});
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+  const result = streamText({
+    model: openai("gpt-5.4-mini"),
+    messages: await convertToModelMessages(messages),
+  });
+  return result.toUIMessageStreamResponse();
+}
+```
+
+</Tab>
+<Tab value="OpenAI SDK">
+
+```ts title="app/api/chat/route.ts"
+import OpenAI from "openai";
+
+const openai = new OpenAI({
+  baseURL: "https://oai.helicone.ai/v1",
+  defaultHeaders: {
+    "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`,
+  },
+});
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const stream = await openai.chat.completions.create({
+    model: "gpt-5.4-mini",
+    messages,
+    stream: true,
+  });
+  return new Response(stream.toReadableStream());
+}
+```
+
+If you're calling the OpenAI SDK directly, you'll also need to adapt the response into a stream `useChatRuntime` understands. The AI SDK tab above handles this for you.
+
+</Tab>
+</Tabs>
+
+</Step>
+<Step>
+
+### Verify in the dashboard
+
+Send a message through your assistant. The call should appear in the Helicone dashboard within a few seconds, with token counts, latency, and the full prompt and completion text.
+
+If nothing appears, check the request in your network tab. The host should be `oai.helicone.ai`, not `api.openai.com`; the request should carry `Helicone-Auth` (added explicitly above) and `Authorization` (added automatically by the OpenAI client from `OPENAI_API_KEY`).
+
+</Step>
+</Steps>
+
+## Notes
+
+- **Server-side only.** Never set the Helicone key in client code; the proxy receives your provider key and must run server-side.
+- **Other providers.** For Anthropic, Gemini, and others, swap the base URL: see Helicone's [provider docs](https://docs.helicone.ai/getting-started/integration-method/gateway).
+- **Custom metadata.** Add `Helicone-User-Id`, `Helicone-Property-*`, or session headers per request to filter and aggregate in the dashboard. The headers are in the [request headers reference](https://docs.helicone.ai/helicone-headers/header-directory).
+- **Streaming, tools, attachments** all keep working unchanged because Helicone wraps the underlying provider transparently.
+
+## Related
+
+<Cards>
+  <Card
+    title="Pick a runtime"
+    description="Choose a backend integration; Helicone pairs with any of them."
+    href="/docs/runtimes/pick-a-runtime"
+  />
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="AI SDK runtime"
+    description="The most common pairing: AI SDK route handler proxied through Helicone."
+    href="/docs/runtimes/ai-sdk/v6"
+  />
+</Cards>

package/.docs/raw/docs/integrations/observability/langfuse.mdx

@@ -0,0 +1,156 @@
+---
+title: Langfuse
+description: Trace AI SDK calls into Langfuse via OpenTelemetry for tracing, evals, and prompt management.
+---
+
+[Langfuse](https://langfuse.com/) is an open-source LLM observability platform. It gives you a hierarchical trace per request (planner → tool calls → final LLM step), prompt-level analytics, datasets, and LLM-as-judge evals. Self-hostable, OpenTelemetry-native.
+
+Pick Langfuse when you want to see the agent's full call tree inside a single turn. It's complementary to [Helicone](/docs/integrations/observability/helicone), which proxies and logs individual provider calls; many teams run both, with Helicone capturing the request log and Langfuse capturing the trace.
+
+## How it works
+
+```
+your route  ──►  AI SDK streamText (with experimental_telemetry)
+                  │
+                  ▼
+                  OpenTelemetry SDK  ──►  LangfuseSpanProcessor  ──►  Langfuse
+```
+
+Langfuse subscribes to OpenTelemetry spans the AI SDK already emits when telemetry is enabled. No proxy, no wrapping; the SDK ships spans and Langfuse renders them.
+
+## Setup
+
+<Steps>
+<Step>
+
+### Get Langfuse credentials
+
+Sign up at [langfuse.com](https://langfuse.com/) (or self-host) and create a project. Copy the public and secret keys from project settings.
+
+```sh title=".env.local"
+LANGFUSE_PUBLIC_KEY=pk-lf-...
+LANGFUSE_SECRET_KEY=sk-lf-...
+LANGFUSE_BASE_URL=https://cloud.langfuse.com
+```
+
+The base URL is region-specific: `https://cloud.langfuse.com` (EU), `https://us.cloud.langfuse.com`, or your self-hosted URL.
+
+</Step>
+<Step>
+
+### Install the OTel and Langfuse packages
+
+<InstallCommand npm={["@langfuse/tracing", "@langfuse/otel", "@opentelemetry/sdk-node"]} />
+
+`@langfuse/tracing` provides the helpers that label traces with user, session, and trace name. `@langfuse/otel` provides the span processor. `@opentelemetry/sdk-node` is the OTel SDK.
+
+</Step>
+<Step>
+
+### Initialize OpenTelemetry once at startup
+
+Create an instrumentation file that boots the OTel SDK and registers the Langfuse span processor. In Next.js this goes in `instrumentation.ts` so it runs once per server process. Export the processor at module scope so other code can call `forceFlush()` on it.
+
+```ts title="instrumentation.ts"
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { LangfuseSpanProcessor } from "@langfuse/otel";
+
+export const langfuseSpanProcessor = new LangfuseSpanProcessor();
+
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+
+  const sdk = new NodeSDK({
+    spanProcessors: [langfuseSpanProcessor],
+  });
+  sdk.start();
+}
+```
+
+`NEXT_RUNTIME !== "nodejs"` skips the edge runtime, where OTel doesn't run. On Next.js 14 or earlier, also set `experimental.instrumentationHook = true` in `next.config.mjs`:
+
+```js title="next.config.mjs"
+const nextConfig = {
+  experimental: { instrumentationHook: true },
+};
+export default nextConfig;
+```
+
+</Step>
+<Step>
+
+### Wrap AI SDK calls with `propagateAttributes`
+
+Enable telemetry with `experimental_telemetry: { isEnabled: true }`, and wrap each call in `propagateAttributes` from `@langfuse/tracing` to set the trace name and group traces by user / session.
+
+```ts title="app/api/chat/route.ts"
+import { openai } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages } from "ai";
+import type { UIMessage } from "ai";
+import { propagateAttributes } from "@langfuse/tracing";
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+
+  const userId = "<resolve from your session>";
+  const sessionId = "<resolve from your thread state>";
+
+  const result = await propagateAttributes(
+    { traceName: "chat-completion", userId, sessionId },
+    async () =>
+      streamText({
+        model: openai("gpt-4o"),
+        messages: await convertToModelMessages(messages),
+        experimental_telemetry: { isEnabled: true },
+      }),
+  );
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+`traceName` becomes the trace label in the Langfuse dashboard. `userId` and `sessionId` are the canonical Langfuse filter dimensions; pass real values from your auth and thread state, not literal strings.
+
+</Step>
+<Step>
+
+### Run and verify
+
+Send a message through your assistant. Within a few seconds, a trace should appear in your Langfuse dashboard with:
+
+- The trace name set by `traceName`.
+- A child span per LLM call and per tool call.
+- Full prompt, completion, and token usage on each span.
+- The metadata you passed (user, session, custom keys) as filters.
+
+If nothing appears, check the server logs for OTel errors and confirm `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` are loaded in the runtime that handles the request.
+
+</Step>
+</Steps>
+
+## Notes
+
+- **Serverless flush.** On serverless platforms the function exits before OTel flushes its buffer, dropping traces. Import the processor exported in the previous step and call `await langfuseSpanProcessor.forceFlush()` before responding, or use the runtime's `waitUntil` API. Langfuse's docs cover the deployment-specific patterns.
+- **Self-hosting.** Point `LANGFUSE_BASE_URL` at your self-hosted instance. The integration is otherwise identical.
+- **Sampling.** For high-traffic apps, configure OTel sampling on `NodeSDK` to keep cost predictable. Langfuse can also sample at the project level.
+- **Pairing with Helicone.** They are complementary: Helicone proxies and logs every request; Langfuse traces the agent. Many teams use both.
+
+## Related
+
+<Cards>
+  <Card
+    title="LangSmith"
+    description="LangChain ecosystem alternative, uses wrapAISDK instead of OpenTelemetry."
+    href="/docs/integrations/observability/langsmith"
+  />
+  <Card
+    title="Helicone"
+    description="Proxy-based request logging with cost, latency, and prompt diffs per call."
+    href="/docs/integrations/observability/helicone"
+  />
+  <Card
+    title="AI SDK runtime"
+    description="The runtime that emits the telemetry Langfuse consumes."
+    href="/docs/runtimes/ai-sdk/v6"
+  />
+</Cards>

package/.docs/raw/docs/integrations/observability/langsmith.mdx

@@ -0,0 +1,146 @@
+---
+title: LangSmith
+description: Trace AI SDK calls into LangSmith with the wrapAISDK helper.
+---
+
+import { LangChainIcon } from "@/components/icons/langchain";
+
+[LangSmith](https://www.langchain.com/langsmith) is LangChain's observability and eval platform. If you are already in the LangChain or LangGraph ecosystem, LangSmith is the natural pairing: traces, datasets, prompt versioning, and LLM-as-judge evals share state with the rest of the LangChain stack.
+
+This page covers the **AI SDK** path. If you use [`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph), tracing flows through LangGraph Cloud automatically; you only need this guide when your route handler talks to AI SDK directly.
+
+## How it works
+
+LangSmith provides a wrapper around the `ai` namespace. You call `wrapAISDK(ai)`, get back the same exports (`generateText`, `streamText`, `generateObject`, `streamObject`), and use those in place of the originals. Every call is then traced.
+
+```
+your route  ──►  wrapped streamText  ──►  LangSmith client  ──►  LangSmith
+```
+
+## Setup
+
+<Steps>
+<Step>
+
+### Get LangSmith credentials
+
+Sign up at [smith.langchain.com](https://smith.langchain.com/) and copy an API key from settings.
+
+```sh title=".env.local"
+LANGSMITH_TRACING=true
+LANGSMITH_API_KEY=lsv2_pt_...
+LANGSMITH_PROJECT=assistant-ui
+```
+
+`LANGSMITH_PROJECT` controls which project receives traces; the default project applies if you omit it. See LangSmith's [environment variable reference](https://docs.langchain.com/langsmith/how_to_environment_variables) for the full list.
+
+</Step>
+<Step>
+
+### Install the LangSmith SDK
+
+<InstallCommand npm={["langsmith"]} />
+
+</Step>
+<Step>
+
+### Wrap the AI SDK
+
+`wrapAISDK` re-exports `generateText`, `streamText`, `generateObject`, and `streamObject` with tracing enabled. Use the wrapped versions in your route.
+
+```ts title="app/api/chat/route.ts"
+import * as ai from "ai";
+import { wrapAISDK } from "langsmith/experimental/vercel";
+import { openai } from "@ai-sdk/openai";
+import type { UIMessage } from "ai";
+
+const { streamText } = wrapAISDK(ai);
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-4o"),
+    messages: await ai.convertToModelMessages(messages),
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+`convertToModelMessages` is not part of the wrapper, so import it from `ai` directly.
+
+</Step>
+<Step>
+
+### Add metadata for grouping (optional)
+
+Pass a `langsmith` provider option to tag traces with user, session, or run identifiers. Use `createLangSmithProviderOptions` to build the value:
+
+```ts
+import { createLangSmithProviderOptions } from "langsmith/experimental/vercel";
+
+const result = streamText({
+  model: openai("gpt-4o"),
+  messages: await ai.convertToModelMessages(messages),
+  providerOptions: {
+    langsmith: createLangSmithProviderOptions({
+      name: "chat-completion",
+      metadata: { userId, threadId },
+    }),
+  },
+});
+```
+
+`name` becomes the run name in LangSmith. Traces filter by the metadata fields you pass; resolve `userId` and `threadId` from your auth and thread state, don't ship literal strings.
+
+</Step>
+<Step>
+
+### Run and verify
+
+Send a message. The trace should appear in your LangSmith project within seconds. Confirm:
+
+- A new run named according to `name` (or the default `streamText`).
+- Inputs (messages), outputs (completion), token usage, and latency are populated.
+- Metadata fields appear as filters.
+
+</Step>
+</Steps>
+
+## Notes
+
+- **Serverless flush.** Serverless functions exit before LangSmith flushes batched traces. Before returning, force the flush with the `Client` from `langsmith`:
+
+  ```ts
+  import { Client } from "langsmith";
+  const client = new Client();
+  // ...inside your route handler, after streamText:
+  await client.awaitPendingTraceBatches();
+  ```
+
+  Without this you will lose traces on Vercel, AWS Lambda, and similar platforms.
+- **`experimental_telemetry` vs `wrapAISDK`.** The AI SDK has a generic `experimental_telemetry` flag that emits OpenTelemetry spans (used by [Langfuse](/docs/integrations/observability/langfuse)). `wrapAISDK` is LangSmith's own path; you do not need to set `experimental_telemetry` when using it.
+- **LangGraph users.** If your backend is LangGraph Cloud, prefer the LangGraph runtime; tracing is built in. Use `wrapAISDK` only when calling AI SDK directly outside of LangGraph.
+- **Version requirements.** LangSmith documents AI SDK v5 as the minimum and `langsmith >= 0.3.63`. The wrapper continues to work against v6 in practice; if you hit an incompatibility, check LangSmith's release notes.
+
+## Related
+
+<Cards>
+  <Card
+    icon={<LangChainIcon width={20} height={20} className="text-[#7FC8FF]" />}
+    title="LangGraph runtime"
+    description="If your backend is LangGraph, tracing flows through LangGraph Cloud automatically."
+    href="/docs/runtimes/langgraph"
+  />
+  <Card
+    title="Langfuse"
+    description="OpenTelemetry-based alternative; OSS and self-hostable."
+    href="/docs/integrations/observability/langfuse"
+  />
+  <Card
+    title="AI SDK runtime"
+    description="The runtime that ferries traces from the route to the chat UI."
+    href="/docs/runtimes/ai-sdk/v6"
+  />
+</Cards>