@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.5

package/.docs/raw/memory/semantic-recall.mdx

@@ -30,16 +30,15 @@ After getting a response from the LLM, all new messages (user, assistant, and to
 
 Semantic recall is enabled by default, so if you give your agent memory it will be included:
 
-```typescript {9}
+```typescript {8}
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 
 const agent = new Agent({
   id: "support-agent",
   name: "SupportAgent",
   instructions: "You are a helpful support agent.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory(),
 });
 ```
@@ -109,11 +108,12 @@ The simplest way is to use a `provider/model` string with autocomplete support:
 ```ts {7}
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 const agent = new Agent({
   memory: new Memory({
     // ... other memory options
-    embedder: "openai/text-embedding-3-small", // TypeScript autocomplete supported
+    embedder: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   }),
 });
 ```
@@ -129,15 +129,15 @@ The model router automatically handles API key detection from environment variab
 
 You can also use AI SDK embedding models directly:
 
-```ts {3,8}
+```ts {2,7}
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 const agent = new Agent({
   memory: new Memory({
     // ... other memory options
-    embedder: openai.embedding("text-embedding-3-small"),
+    embedder: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   }),
 });
 ```

package/.docs/raw/memory/storage/memory-with-libsql.mdx

@@ -28,7 +28,6 @@ To add LibSQL memory to an agent use the `Memory` class and create a new `storag
 ```typescript title="src/mastra/agents/example-libsql-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore } from "@mastra/libsql";
 
 export const libsqlAgent = new Agent({
@@ -36,7 +35,7 @@ export const libsqlAgent = new Agent({
   name: "LibSQL Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'libsql-agent-storage',
@@ -64,7 +63,6 @@ Add the following to your agent:
 ```typescript title="src/mastra/agents/example-libsql-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 import { fastembed } from "@mastra/fastembed";
 
@@ -73,7 +71,7 @@ export const libsqlAgent = new Agent({
   name: "LibSQL Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'libsql-agent-storage',

package/.docs/raw/memory/storage/memory-with-mongodb.mdx

@@ -30,7 +30,6 @@ To add MongoDB memory to an agent use the `Memory` class and create a new `stora
 ```typescript title="src/mastra/agents/example-mongodb-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { MongoDBStore } from "@mastra/mongodb";
 
 export const mongodbAgent = new Agent({
@@ -38,7 +37,7 @@ export const mongodbAgent = new Agent({
   name: "mongodb-agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new MongoDBStore({
       url: process.env.MONGODB_URI!,
@@ -71,7 +70,6 @@ Add the following to your agent:
 ```typescript title="src/mastra/agents/example-mongodb-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { MongoDBStore, MongoDBVector } from "@mastra/mongodb";
 import { fastembed } from "@mastra/fastembed";
 
@@ -80,7 +78,7 @@ export const mongodbAgent = new Agent({
   name: "mongodb-agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new MongoDBStore({
       url: process.env.MONGODB_URI!,

package/.docs/raw/memory/storage/memory-with-pg.mdx

@@ -29,7 +29,6 @@ To add PostgreSQL memory to an agent use the `Memory` class and create a new `st
 ```typescript title="src/mastra/agents/example-pg-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { PostgresStore } from "@mastra/pg";
 
 export const pgAgent = new Agent({
@@ -37,7 +36,7 @@ export const pgAgent = new Agent({
   name: "PG Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new PostgresStore({
       id: 'pg-agent-storage',
@@ -65,7 +64,6 @@ Add the following to your agent:
 ```typescript title="src/mastra/agents/example-pg-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { PostgresStore, PgVector } from "@mastra/pg";
 import { fastembed } from "@mastra/fastembed";
 
@@ -74,7 +72,7 @@ export const pgAgent = new Agent({
   name: "PG Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new PostgresStore({
       id: 'pg-agent-storage',

package/.docs/raw/memory/storage/memory-with-upstash.mdx

@@ -34,7 +34,6 @@ To add Upstash memory to an agent use the `Memory` class and create a new `stora
 ```typescript title="src/mastra/agents/example-upstash-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { UpstashStore } from "@mastra/upstash";
 
 export const upstashAgent = new Agent({
@@ -42,7 +41,7 @@ export const upstashAgent = new Agent({
   name: "Upstash Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new UpstashStore({
       id: 'upstash-agent-storage',
@@ -71,7 +70,6 @@ Add the following to your agent:
 ```typescript title="src/mastra/agents/example-upstash-agent.ts" showLineNumbers copy
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { UpstashStore, UpstashVector } from "@mastra/upstash";
 import { fastembed } from "@mastra/fastembed";
 
@@ -80,7 +78,7 @@ export const upstashAgent = new Agent({
   name: "Upstash Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new UpstashStore({
       id: 'upstash-agent-storage',

package/.docs/raw/memory/threads-and-resources.mdx

@@ -56,7 +56,7 @@ export const testAgent = new Agent({
     options: {
       threads: {
         generateTitle: {
-          model: openai("gpt-4.1-nano"),
+          model: "openai/gpt-4.1-nano",
           instructions:
             "Generate a concise title based on the user's first message",
         },
@@ -80,8 +80,8 @@ export const testAgent = new Agent({
           model: ({ requestContext }) => {
             const userTier = requestContext.get("userTier");
             return userTier === "premium"
-              ? openai("gpt-4.1")
-              : openai("gpt-4.1-nano");
+              ? "openai/gpt-5.1"
+              : "openai/gpt-4.1-nano";
           },
           instructions: ({ requestContext }) => {
             const language = requestContext.get("userLanguage") || "English";

package/.docs/raw/memory/working-memory.mdx

@@ -24,17 +24,16 @@ Working memory can persist at two different scopes:
 
 Here's a minimal example of setting up an agent with working memory:
 
-```typescript {12-15}
+```typescript {11-14}
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 
 // Create agent with working memory enabled
 const agent = new Agent({
   id: "personal-assistant",
   name: "PersonalAssistant",
   instructions: "You are a helpful personal assistant.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   memory: new Memory({
     options: {
       workingMemory: {
@@ -378,6 +377,6 @@ await memory.updateWorkingMemory({
 
 ## Examples
 
-- [Working memory with template](/examples/v1/memory/working-memory-template)
-- [Working memory with schema](/examples/v1/memory/working-memory-schema)
+- [Working memory with template](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-template)
+- [Working memory with schema](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-schema)
 - [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example) - Complete example showing resource-scoped memory persistence

package/.docs/raw/{logging.mdx → observability/logging.mdx}

@@ -11,7 +11,7 @@ When deploying to Mastra Cloud, logs are shown on the [Logs](/docs/v1/deployment
 
 ## Configuring logs with PinoLogger
 
-When [initializing a new Mastra project](/guides/v1/quickstarts/standalone-server) using the CLI, `PinoLogger` is included by default.
+When [initializing a new Mastra project](/guides/v1/getting-started/quickstart) using the CLI, `PinoLogger` is included by default.
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
 import { Mastra } from "@mastra/core/mastra";

package/.docs/raw/observability/overview.mdx

@@ -43,11 +43,11 @@ export const mastra = new Mastra({
 
 With this basic setup, you will see Traces and Logs in both Studio and in Mastra Cloud.
 
-We also support various external tracing providers like Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the [Tracing](/docs/v1/observability/tracing/overview) documentation.
+We also support various external tracing providers like MLflow, Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the [Tracing](/docs/v1/observability/tracing/overview) documentation.
 
 ## What's Next?
 
 - **[Set up Tracing](/docs/v1/observability/tracing/overview)**: Configure tracing for your application
-- **[Configure Logging](/docs/v1/logging)**: Add structured logging
+- **[Configure Logging](/docs/v1/observability/logging)**: Add structured logging
 - **[View Examples](/examples/v1/observability/basic-ai-tracing)**: See observability in action
 - **[API Reference](/reference/v1/observability/tracing/instances)**: Detailed configuration options

package/.docs/raw/observability/tracing/exporters/otel.mdx

@@ -11,13 +11,13 @@ The OpenTelemetry exporter is currently **experimental**. APIs and configuration
 
 :::
 
-The OpenTelemetry (OTEL) exporter sends your traces to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, Dash0, Traceloop, Laminar, and more.
+The OpenTelemetry (OTEL) exporter sends your traces to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, MLflow, Dash0, Traceloop, Laminar, and more.
 
 ## Installation
 
 Each provider requires specific protocol packages. Install the base exporter plus the protocol package for your provider:
 
-### For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar)
+### For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar, MLflow)
 
 ```bash npm2yarn
 npm install @mastra/otel-exporter@beta @opentelemetry/exporter-trace-otlp-proto
@@ -37,6 +37,25 @@ npm install @mastra/otel-exporter@beta @opentelemetry/exporter-trace-otlp-http
 
 ## Provider Configurations
 
+
+### MLflow
+
+[MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) supports native Mastra tracing through its OTLP endpoint at `/v1/traces`. Use the `custom` provider with HTTP/Protobuf and include the experiment header so traces land in the correct MLflow experiment:
+
+```typescript title="src/mastra/index.ts"
+new OtelExporter({
+  provider: {
+    custom: {
+      endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`,
+      protocol: "http/protobuf",
+      headers: {
+        "x-mlflow-experiment-id": process.env.MLFLOW_EXPERIMENT_ID,
+      },
+    },
+  },
+})
+```
+
 ### Dash0
 
 [Dash0](https://www.dash0.com/) provides real-time observability with automatic insights.

package/.docs/raw/observability/tracing/exporters/posthog.mdx

@@ -0,0 +1,107 @@
+---
+title: "PostHog Exporter | Tracing | Observability"
+description: "Send traces to PostHog for AI observability and analytics"
+---
+
+# PostHog Exporter
+
+[PostHog](https://posthog.com/) is an analytics platform with AI observability features for monitoring LLM applications. The PostHog exporter sends your traces to PostHog as structured events, providing insights into token usage, costs, latency, and conversation flows.
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/posthog@beta
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **PostHog Account**: Sign up at [posthog.com](https://posthog.com/)
+2. **Project API Key**: Get your project API key from PostHog Settings → Project API Key
+3. **Environment Variables**: Set your credentials
+
+```bash title=".env"
+POSTHOG_API_KEY=phc_xxxxxxxxxxxxxxxx
+POSTHOG_HOST=https://us.i.posthog.com  # Optional: EU region or self-hosted URL
+```
+
+### Basic Setup
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { PosthogExporter } from "@mastra/posthog";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      posthog: {
+        serviceName: "my-service",
+        exporters: [
+          new PosthogExporter({
+            apiKey: process.env.POSTHOG_API_KEY,
+          }),
+        ],
+      },
+    },
+  }),
+});
+```
+
+## Configuration Options
+
+### Complete Configuration
+
+```typescript
+new PosthogExporter({
+  // Required credentials
+  apiKey: process.env.POSTHOG_API_KEY!,
+
+  // Optional settings
+  host: "https://us.i.posthog.com", // Default: US region
+  // or "https://eu.i.posthog.com" for EU region
+  // or your self-hosted URL
+
+  // Batching configuration
+  flushAt: 20, // Batch size (default: 20)
+  flushInterval: 10000, // Flush interval in ms (default: 10000)
+  serverless: false, // Serverless mode: flushAt=10, flushInterval=2000
+
+  // User identification
+  defaultDistinctId: "anonymous", // Fallback if no userId in metadata
+
+  // Privacy settings
+  enablePrivacyMode: false, // Excludes input/output from generation events
+
+  // Diagnostic logging
+  logLevel: "info", // debug | info | warn | error
+});
+```
+
+### Serverless Mode
+
+Optimized batching for serverless environments:
+
+```typescript
+new PosthogExporter({
+  apiKey: process.env.POSTHOG_API_KEY!,
+  serverless: true, // Configures smaller batches for faster flushing
+});
+```
+
+### Privacy Mode
+
+Exclude input/output data from generation events while preserving token metrics:
+
+```typescript
+new PosthogExporter({
+  apiKey: process.env.POSTHOG_API_KEY!,
+  enablePrivacyMode: true, // Removes $ai_input and $ai_output_choices
+});
+```
+
+## Related
+
+- [Tracing Overview](/docs/v1/observability/tracing/overview)
+- [PostHog Documentation](https://posthog.com/docs)

package/.docs/raw/observability/tracing/overview.mdx

@@ -97,7 +97,7 @@ In addition to the internal exporters, Mastra supports integration with popular
 - **[Langfuse](/docs/v1/observability/tracing/exporters/langfuse)** - Sends traces to the Langfuse open-source LLM engineering platform
 - **[LangSmith](/docs/v1/observability/tracing/exporters/langsmith)** - Pushes traces into LangSmith's observability and evaluation toolkit
 - **[OpenTelemetry](/docs/v1/observability/tracing/exporters/otel)** - Deliver traces to any OpenTelemetry-compatible observability system
-  - Supports: Dash0, Laminar, New Relic, SigNoz, Traceloop, Zipkin, and others!
+  - Supports: Dash0, MLflow, Laminar, New Relic, SigNoz, Traceloop, Zipkin, and others!
 
 ## Sampling Strategies
 
@@ -619,7 +619,7 @@ console.log("Trace ID:", finalState.traceId);
 Once you have a trace ID, you can:
 
 1. **Look up traces in Studio**: Navigate to the traces view and search by ID
-2. **Query traces in external platforms**: Use the ID in Langfuse, Braintrust, or your observability platform
+2. **Query traces in external platforms**: Use the ID in Langfuse, Braintrust, MLflow, or your observability platform
 3. **Correlate with logs**: Include the trace ID in your application logs for cross-referencing
 4. **Share for debugging**: Provide trace IDs to support teams or developers for investigation
 
@@ -770,6 +770,7 @@ Mastra automatically creates spans for:
 - [Arize](/reference/v1/observability/tracing/exporters/arize) - Arize Phoenix and Arize AX integration
 - [Braintrust](/reference/v1/observability/tracing/exporters/braintrust) - Braintrust integration
 - [Langfuse](/reference/v1/observability/tracing/exporters/langfuse) - Langfuse integration
+- [MLflow](/reference/v1/observability/tracing/exporters/otel#mlflow) - MLflow OTLP endpoint setup
 - [OpenTelemetry](/reference/v1/observability/tracing/exporters/otel) - OTEL-compatible platforms
 
 ### Processors

package/.docs/raw/rag/chunking-and-embedding.mdx

@@ -83,12 +83,8 @@ The simplest way is to use Mastra's model router with `provider/model` strings:
 import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 import { embedMany } from "ai";
 
-const embeddingModel = new ModelRouterEmbeddingModel(
-  "openai/text-embedding-3-small",
-);
-
 const { embeddings } = await embedMany({
-  model: embeddingModel,
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   values: chunks.map((chunk) => chunk.text),
 });
 ```
@@ -105,11 +101,11 @@ The model router automatically handles API key detection from environment variab
 You can also use AI SDK embedding models directly:
 
 ```ts showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { embedMany } from "ai";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 const { embeddings } = await embedMany({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   values: chunks.map((chunk) => chunk.text),
 });
 ```
@@ -129,19 +125,22 @@ Here are some supported models:
 OpenAI (text-embedding-3 models):
 
 ```ts
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
 const { embeddings } = await embedMany({
-  model: openai.embedding("text-embedding-3-small", {
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  options: {
     dimensions: 256, // Only supported in text-embedding-3 and later
-  }),
+  },
   values: chunks.map((chunk) => chunk.text),
 });
 ```
 
-Google (text-embedding-004):
+Google (text-embedding-001):
 
 ```ts
 const { embeddings } = await embedMany({
-  model: google.textEmbeddingModel("text-embedding-004", {
+  model: "google/gemini-embedding-001", {
     outputDimensionality: 256, // Truncates excessive values from the end
   }),
   values: chunks.map((chunk) => chunk.text),
@@ -158,8 +157,6 @@ Here's an example showing document processing and embedding generation with both
 
 ```ts showLineNumbers copy
 import { embedMany } from "ai";
-import { openai } from "@ai-sdk/openai";
-import { cohere } from "@ai-sdk/cohere";
 
 import { MDocument } from "@mastra/rag";
 
@@ -177,16 +174,18 @@ const chunks = await doc.chunk({
 });
 
 // Generate embeddings with OpenAI
-const { embeddings: openAIEmbeddings } = await embedMany({
-  model: openai.embedding("text-embedding-3-small"),
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
+const { embeddings } = await embedMany({
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   values: chunks.map((chunk) => chunk.text),
 });
 
 // OR
 
 // Generate embeddings with Cohere
-const { embeddings: cohereEmbeddings } = await embedMany({
-  model: cohere.embedding("embed-english-v3.0"),
+const { embeddings } = await embedMany({
+  model: "cohere/embed-english-v3.0",
   values: chunks.map((chunk) => chunk.text),
 });
 

package/.docs/raw/rag/overview.mdx

@@ -20,7 +20,6 @@ To implement RAG, you process your documents into chunks, create embeddings, sto
 
 ```ts showLineNumbers copy
 import { embedMany } from "ai";
-import { openai } from "@ai-sdk/openai";
 import { PgVector } from "@mastra/pg";
 import { MDocument } from "@mastra/rag";
 import { z } from "zod";
@@ -36,9 +35,11 @@ const chunks = await doc.chunk({
 });
 
 // 3. Generate embeddings; we need to pass the text of each chunk
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
 const { embeddings } = await embedMany({
   values: chunks.map((chunk) => chunk.text),
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small")
 });
 
 // 4. Store in vector database