@assistant-ui/mcp-docs-server 0.1.30 → 0.1.32

package/.docs/raw/docs/integrations/frameworks/mastra/separate-server.mdx

@@ -0,0 +1,201 @@
+---
+title: Separate server integration
+description: Run Mastra as a standalone server with assistant-ui as a separate frontend.
+---
+
+import { MastraIcon } from "@/components/icons/mastra";
+import { VercelIcon } from "@/components/icons/vercel";
+
+Run Mastra as its own service and have the assistant-ui frontend hit it over HTTP. The two halves can deploy, scale, and version independently. The tradeoff is one extra hop and CORS to configure.
+
+For the simpler in-process variant, see [full-stack](/docs/integrations/frameworks/mastra/full-stack) instead.
+
+## Setup
+
+The setup has two halves. Steps 1 to 4 happen in the **Mastra server** project; steps 5 to 7 happen in a **separate assistant-ui frontend** project. You'll have two terminals open by the end: one for each dev server.
+
+<Steps>
+
+<Step>
+
+### Create the Mastra server project
+
+In a directory separate from your frontend, scaffold a Mastra project:
+
+```sh
+npx create-mastra@latest
+```
+
+Follow the wizard's prompts. When it finishes, change into the new directory and add the AI SDK adapter:
+
+```sh
+cd your-mastra-server
+```
+
+<InstallCommand npm={["@mastra/ai-sdk@latest"]} />
+
+Set the model provider keys (`OPENAI_API_KEY`, etc.) in `.env.development`. The `create-mastra` wizard prompts for some keys, but verify all the providers you plan to call are present.
+
+</Step>
+
+<Step>
+
+### Define an agent
+
+```ts title="src/mastra/agents/chefAgent.ts"
+import { Agent } from "@mastra/core/agent";
+
+export const chefAgent = new Agent({
+  name: "chef-agent",
+  instructions:
+    "You are Michel, a practical and experienced home chef. " +
+    "You help people cook with whatever ingredients they have available.",
+  model: "openai/gpt-5.4-nano",
+});
+```
+
+</Step>
+
+<Step>
+
+### Register the agent, chat route, and CORS
+
+Open the Mastra entry point. You will set three things in the same `Mastra` constructor: the agent, a chat route, and CORS for the frontend's origin.
+
+```ts title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { chefAgent } from "./agents/chefAgent";
+import { chatRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  agents: { chefAgent },
+  server: {
+    cors: {
+      origin: process.env.FRONTEND_ORIGIN ?? "http://localhost:3000",
+      credentials: true,
+    },
+    apiRoutes: [
+      chatRoute({ path: "/chat/:agentId" }),
+    ],
+  },
+});
+```
+
+A few things to note:
+
+- `:agentId` matches the **JavaScript key** in the `agents` object, not the agent's `name` field. So `chefAgent` is reachable at `/chat/chefAgent` (camelCase), not `/chat/chef-agent`.
+- Add more agents to the `agents` object and they all become callable through this single route.
+- `FRONTEND_ORIGIN` should be set to your deployed frontend's URL in production. Without CORS configured, the browser blocks the request and the chat silently fails.
+
+</Step>
+
+<Step>
+
+### Run the Mastra server
+
+```bash npm2yarn
+npm run dev
+```
+
+The server starts on `http://localhost:4111` by default. Leave it running for the rest of the steps.
+
+</Step>
+
+<Step>
+
+### Initialize the assistant-ui frontend
+
+In a **different directory** from the Mastra server, scaffold the frontend:
+
+```sh title="New project"
+npx assistant-ui@latest create
+```
+
+```sh title="Existing project"
+npx assistant-ui@latest init
+```
+
+This creates a default chat page and a local API route at `app/api/chat/route.ts`. You won't use the local route, since the agent runs on the separate Mastra server; delete it once the next step is wired.
+
+</Step>
+
+<Step>
+
+### Point the runtime at the Mastra server
+
+Open the file containing `useChatRuntime` (typically `app/assistant.tsx`) and pass an explicit `api` URL:
+
+```tsx title="app/assistant.tsx" {8}
+"use client";
+
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { AssistantChatTransport, useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { Thread } from "@/components/assistant-ui/thread";
+
+export const Assistant = () => {
+  const runtime = useChatRuntime({
+    transport: new AssistantChatTransport({
+      api: process.env.NEXT_PUBLIC_MASTRA_URL!,
+    }),
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+};
+```
+
+Set the URL in your frontend's environment:
+
+```sh title=".env.local"
+NEXT_PUBLIC_MASTRA_URL=http://localhost:4111/chat/chefAgent
+```
+
+`NEXT_PUBLIC_*` makes the URL available in the browser. In production, point this at your deployed Mastra server. Mastra itself uses `.env.development` for its server keys; the two projects keep separate environment files.
+
+</Step>
+
+<Step>
+
+### Run and verify
+
+Make sure the Mastra server (step 4) is still running in its own terminal, then start the frontend in a new terminal:
+
+```bash npm2yarn
+npm run dev
+```
+
+Open `http://localhost:3000`, send a message, and confirm:
+
+- The response streams in token by token.
+- The network tab shows the `POST` going to `http://localhost:4111/chat/chefAgent`, not the local `/api/chat`.
+- No CORS errors in the console; if you see `blocked by CORS policy`, revisit step 3.
+
+</Step>
+
+</Steps>
+
+## Notes
+
+- **Auth between frontend and Mastra**: the example above is open. In production, gate the Mastra route with a header or cookie check and forward credentials from the frontend (`AssistantChatTransport` accepts `headers` and `credentials` options).
+- **Single agent vs router**: `chatRoute({ path: "/chat/:agentId" })` works for any agent registered on the `Mastra` instance. Switching agents from the frontend is a matter of pointing `NEXT_PUBLIC_MASTRA_URL` at a different agent ID.
+- **Advanced Mastra features** (memory, tools, workflows, evals) live in the agent definition. The frontend sees only the resulting stream. See the [Mastra docs](https://mastra.ai/docs).
+
+## Related
+
+<Cards>
+  <Card
+    icon={<MastraIcon width={20} height={20} />}
+    title="Full-stack integration"
+    description="Run Mastra inside your Next.js API routes for a single deploy target."
+    href="/docs/integrations/frameworks/mastra/full-stack"
+  />
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="AI SDK runtime"
+    description="The runtime that handles the client side of this integration."
+    href="/docs/runtimes/ai-sdk/v6"
+  />
+</Cards>

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

@@ -0,0 +1,162 @@
+---
+title: LLM Gateway Integrations
+description: Route AI chat traffic through OpenAI-compatible LLM gateways (OpenRouter, LiteLLM, Portkey, etc.) for cost, fallback, and BYOK in assistant-ui apps.
+---
+
+import { HeliconeIcon } from "@/components/icons/helicone";
+import { VercelIcon } from "@/components/icons/vercel";
+
+LLM gateways sit between your route handler and the upstream provider. They give you a single endpoint that fronts many providers, plus features like multi-provider fallback, prompt caching, and BYOK (bring-your-own-key) flows. Most are OpenAI API-compatible, so the integration is a `baseURL` swap on `createOpenAI` from `@ai-sdk/openai`.
+
+For pure observability (proxy that logs every call) see [Helicone](/docs/integrations/observability/helicone). The gateways here overlap in spirit but are positioned around routing rather than logging.
+
+## Compare
+
+| Gateway | Base URL | Auth header | Distinguishing feature |
+| --- | --- | --- | --- |
+| [OpenRouter](#openrouter) | `https://openrouter.ai/api/v1` | `Authorization: Bearer <key>` | Catalog of 100+ models with `vendor/model` IDs |
+| [Portkey](#portkey) | `https://api.portkey.ai/v1` | `x-portkey-api-key` | Config-driven multi-provider fallback |
+| [LiteLLM Proxy](#litellm-proxy) | Self-hosted | `Authorization: Bearer <virtual key>` | OSS, self-host, virtual keys per tenant |
+
+If your need is only request logging, Helicone fits the same shape and is documented separately.
+
+## Common pattern
+
+All three gateways below speak OpenAI's API. Wire them with `createOpenAI`:
+
+```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: "<gateway base url>",
+  headers: { /* gateway-specific auth */ },
+});
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+  const result = streamText({
+    model: openai("<model id>"),
+    messages: await convertToModelMessages(messages),
+  });
+  return result.toUIMessageStreamResponse();
+}
+```
+
+The rest of this page is what to put in `baseURL`, `headers`, and `model(...)` for each gateway.
+
+## OpenRouter
+
+[OpenRouter](https://openrouter.ai/) aggregates 100+ models behind one OpenAI-compatible endpoint. The model ID is `provider/model` (e.g., `anthropic/claude-sonnet-4.6`, `openai/gpt-5.4-mini`, `meta-llama/llama-3.3-70b-instruct`).
+
+```sh title=".env.local"
+OPENROUTER_API_KEY=sk-or-...
+SITE_URL=https://your-app.example
+```
+
+```ts title="app/api/chat/route.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages } from "ai";
+import type { UIMessage } from "ai";
+
+const openrouter = createOpenAI({
+  baseURL: "https://openrouter.ai/api/v1",
+  apiKey: process.env.OPENROUTER_API_KEY,
+  headers: {
+    "HTTP-Referer": process.env.SITE_URL ?? "http://localhost:3000",
+    "X-Title": "My App",
+  },
+});
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+  const result = streamText({
+    model: openrouter("anthropic/claude-sonnet-4.6"),
+    messages: await convertToModelMessages(messages),
+  });
+  return result.toUIMessageStreamResponse();
+}
+```
+
+`HTTP-Referer` and `X-Title` are optional attribution headers; OpenRouter shows them in your usage dashboard.
+
+When to pick: you want a single bill across many models, or you let users pick the model from a long list, or you need to run open-weights models without managing the inference yourself.
+
+## Portkey
+
+[Portkey](https://portkey.ai/) is a gateway plus observability with a config-driven router. The differentiating feature is the *config*: a server-defined object that describes routing rules (try Anthropic first, fall back to OpenAI, fall back to a local model), retries, and caching.
+
+```sh title=".env.local"
+PORTKEY_API_KEY=...
+PORTKEY_VIRTUAL_KEY=...
+```
+
+```ts title="app/api/chat/route.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+
+const portkey = createOpenAI({
+  baseURL: "https://api.portkey.ai/v1",
+  apiKey: "no-auth-here",
+  headers: {
+    "x-portkey-api-key": process.env.PORTKEY_API_KEY!,
+    "x-portkey-virtual-key": process.env.PORTKEY_VIRTUAL_KEY!,
+  },
+});
+```
+
+Configs live in the Portkey dashboard; reference them with `x-portkey-config: <config-id>` in the headers when you want a specific routing strategy.
+
+When to pick: you need cross-provider fallback or prompt-cache hit rates that the AI SDK doesn't give you out of the box.
+
+## LiteLLM Proxy
+
+[LiteLLM Proxy](https://docs.litellm.ai/docs/simple_proxy) is OSS and self-hostable. You run it, you configure provider keys server-side, and you hand virtual keys (per-tenant, per-user) to clients. It's the only viable path for BYOK SaaS or air-gapped deployments.
+
+Run the proxy first (Docker, k8s, or a single Node process). Then point the AI SDK at your instance:
+
+```sh title=".env.local"
+LITELLM_BASE_URL=https://litellm.example.com
+LITELLM_VIRTUAL_KEY=sk-...
+```
+
+```ts title="app/api/chat/route.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+
+const litellm = createOpenAI({
+  baseURL: process.env.LITELLM_BASE_URL!,
+  apiKey: process.env.LITELLM_VIRTUAL_KEY!,
+});
+
+const result = streamText({
+  model: litellm("gpt-5.4-mini"),
+  messages: await convertToModelMessages(messages),
+});
+```
+
+Model IDs depend on how you configured the proxy. LiteLLM rewrites them to upstream providers based on your config.
+
+When to pick: self-host requirement, BYOK metering for end-users, or unified billing across providers managed by your platform team.
+
+## Notes
+
+- **Server-side only.** A gateway key is a write capability against your billing account. Never set it in client code; the route handler is the right boundary.
+- **Streaming, tools, attachments.** All three gateways are transparent to the AI SDK; everything that works against OpenAI directly works through them.
+- **Combining with observability.** A gateway and an observability tool are not mutually exclusive. Helicone in front of OpenRouter is a common stack: OpenRouter does the routing, Helicone logs the calls.
+
+## Related
+
+<Cards>
+  <Card
+    icon={<HeliconeIcon width={20} height={20} />}
+    title="Helicone"
+    description="The observability-first proxy. Same shape, different goal."
+    href="/docs/integrations/observability/helicone"
+  />
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="AI SDK runtime"
+    description="The runtime that ferries gateway responses to the chat UI."
+    href="/docs/runtimes/ai-sdk/v6"
+  />
+</Cards>

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

@@ -0,0 +1,185 @@
+---
+title: Integrations
+description: Adapters for Vercel AI SDK, LangChain, LangGraph, Mastra, plus auth, persistence, observability, and tool services — drop into a React chat UI built with assistant-ui.
+---
+
+import { CloudflareIcon } from "@/components/icons/cloudflare";
+import { HeliconeIcon } from "@/components/icons/helicone";
+import { MastraIcon } from "@/components/icons/mastra";
+import { LangfuseIcon } from "@/components/icons/langfuse";
+import { LangChainIcon } from "@/components/icons/langchain";
+import { McpIcon } from "@/components/icons/mcp";
+import { VercelIcon } from "@/components/icons/vercel";
+
+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={<CloudflareIcon width={20} height={20} />}
+      title="Cloudflare Agents"
+      description="Stateful Durable Object agents. Wired through the AI SDK runtime with WebSocket streaming."
+      href="/docs/integrations/frameworks/cloudflare-agents/overview"
+    />
+    <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
+    icon={<McpIcon width={20} height={20} />}
+    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
+    icon={<HeliconeIcon width={20} height={20} />}
+    title="Helicone"
+    description="Observability proxy. Drop-in baseURL swap that logs cost, latency, and prompts."
+    href="/docs/integrations/observability/helicone"
+  />
+  <Card
+    icon={<LangfuseIcon width={20} height={20} />}
+    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>