@mastra/mcp-docs-server 1.0.0-beta.1 → 1.0.0-beta.11

package/.docs/raw/reference/observability/tracing/exporters/langsmith.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: LangSmithExporter | Observability | Mastra Docs"
+title: "Reference: LangSmithExporter | Observability"
 description: LangSmith exporter for Tracing
 ---
 
@@ -20,6 +20,7 @@ new LangSmithExporter(config: LangSmithExporterConfig)
 ```typescript
 interface LangSmithExporterConfig extends ClientConfig, BaseExporterConfig {
   client?: Client;
+  projectName?: string;
 }
 ```
 
@@ -32,7 +33,13 @@ Extends both `ClientConfig` (from LangSmith SDK) and `BaseExporterConfig`:
     {
       name: "apiKey",
       type: "string",
-      description: "LangSmith API key",
+      description: "LangSmith API key. Defaults to LANGSMITH_API_KEY env var.",
+      required: false,
+    },
+    {
+      name: "projectName",
+      type: "string",
+      description: "The LangSmith project to send traces to. Overrides LANGCHAIN_PROJECT env var. Defaults to 'default'.",
       required: false,
     },
     {
@@ -99,11 +106,20 @@ import { LangSmithExporter } from "@mastra/langsmith";
 
 const exporter = new LangSmithExporter({
   apiKey: process.env.LANGSMITH_API_KEY,
+  projectName: "my-project", // Optional: specify which project to send traces to
   apiUrl: "https://api.smith.langchain.com",
   logLevel: "info",
 });
 ```
 
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LANGSMITH_API_KEY` | Your LangSmith API key |
+| `LANGCHAIN_PROJECT` | Default project name for traces (used if `projectName` not specified) |
+| `LANGSMITH_BASE_URL` | API URL for self-hosted instances |
+
 ## Span Type Mapping
 
 | Span Type       | LangSmith Type |

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: OtelExporter | Observability | Mastra Docs"
+title: "Reference: OtelExporter | Observability"
 description: OpenTelemetry exporter for Tracing
 ---
 
@@ -7,12 +7,6 @@ import PropertiesTable from "@site/src/components/PropertiesTable";
 
 # OtelExporter
 
-:::warning
-
-The OtelExporter is currently **experimental**. APIs and configuration options may change in future releases.
-
-:::
-
 Sends Tracing data to any OpenTelemetry-compatible observability platform using standardized GenAI semantic conventions.
 
 ## Constructor
@@ -317,38 +311,6 @@ const exporter = new OtelExporter({
 });
 ```
 
-## Span Mapping
-
-The exporter maps Mastra AI spans to OpenTelemetry spans following GenAI semantic conventions:
-
-### Span Names
-
-- `MODEL_GENERATION` → `chat {model}` or `tool_selection {model}`
-- `TOOL_CALL` → `tool.execute {tool_name}`
-- `AGENT_RUN` → `agent.{agent_id}`
-- `WORKFLOW_RUN` → `workflow.{workflow_id}`
-
-### Span Kinds
-
-- Root agent/workflow spans → `SERVER`
-- LLM calls → `CLIENT`
-- Tool calls → `INTERNAL` or `CLIENT`
-- Workflow steps → `INTERNAL`
-
-### Attributes
-
-The exporter maps to standard OTEL GenAI attributes:
-
-| Mastra Attribute                    | OTEL Attribute                   |
-| ----------------------------------- | -------------------------------- |
-| `model`                             | `gen_ai.request.model`           |
-| `provider`                          | `gen_ai.system`                  |
-| `inputTokens` / `promptTokens`      | `gen_ai.usage.input_tokens`      |
-| `outputTokens` / `completionTokens` | `gen_ai.usage.output_tokens`     |
-| `temperature`                       | `gen_ai.request.temperature`     |
-| `maxOutputTokens`                   | `gen_ai.request.max_tokens`      |
-| `finishReason`                      | `gen_ai.response.finish_reasons` |
-
 ## Protocol Requirements
 
 Different providers require different OTEL exporter packages:
@@ -360,10 +322,38 @@ Different providers require different OTEL exporter packages:
 | HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`  | Traceloop, Custom          |
 | Zipkin        | `@opentelemetry/exporter-zipkin`           | Zipkin collectors          |
 
-## Parent-Child Relationships
 
-The exporter preserves span hierarchy from Mastra's Tracing:
+## Tags Support
+
+The OtelExporter supports trace tagging for categorization and filtering. Tags are only applied to root spans and are stored as the `mastra.tags` attribute.
+
+### Usage
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+### How Tags Are Stored
+
+Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute for maximum backend compatibility:
+
+```json
+{
+  "mastra.tags": "[\"production\",\"experiment-v2\",\"user-request\"]"
+}
+```
+
+:::note
+While the OpenTelemetry specification supports native array attributes, many backends (Jaeger, Zipkin, Tempo) have limited array support. JSON strings ensure consistent behavior across all observability platforms.
+:::
+
+## Related
 
-- Uses `parentSpanId` directly from Mastra spans
-- Maintains correct nesting for agents, workflows, LLM calls, and tools
-- Exports complete traces with all relationships intact
+- [OtelExporter Guide](/docs/v1/observability/tracing/exporters/otel) - Setup guide with provider configurations
+- [OtelBridge](/docs/v1/observability/tracing/bridges/otel) - For bidirectional OTEL context integration
+- [Tracing Overview](/docs/v1/observability/tracing/overview) - General tracing concepts

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

@@ -0,0 +1,132 @@
+---
+title: "Reference: PosthogExporter | Observability"
+description: PostHog exporter for Tracing
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# PosthogExporter
+
+Sends Tracing data to PostHog for AI observability and analytics.
+
+## Constructor
+
+```typescript
+new PosthogExporter(config: PosthogExporterConfig)
+```
+
+## PosthogExporterConfig
+
+```typescript
+interface PosthogExporterConfig extends BaseExporterConfig {
+  apiKey: string;
+  host?: string;
+  flushAt?: number;
+  flushInterval?: number;
+  serverless?: boolean;
+  defaultDistinctId?: string;
+  enablePrivacyMode?: boolean;
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+<PropertiesTable
+  props={[
+    {
+      name: "apiKey",
+      type: "string",
+      description: "PostHog project API key",
+      required: true,
+    },
+    {
+      name: "host",
+      type: "string",
+      description: "PostHog host URL (default: 'https://us.i.posthog.com')",
+      required: false,
+    },
+    {
+      name: "flushAt",
+      type: "number",
+      description: "Batch size before auto-flush (default: 20, serverless: 10)",
+      required: false,
+    },
+    {
+      name: "flushInterval",
+      type: "number",
+      description: "Flush interval in milliseconds (default: 10000, serverless: 2000)",
+      required: false,
+    },
+    {
+      name: "serverless",
+      type: "boolean",
+      description: "Auto-configure for serverless environments (default: false)",
+      required: false,
+    },
+    {
+      name: "defaultDistinctId",
+      type: "string",
+      description: "Fallback user identifier if no userId in metadata (default: 'anonymous')",
+      required: false,
+    },
+    {
+      name: "enablePrivacyMode",
+      type: "boolean",
+      description: "Exclude input/output from generation events (default: false)",
+      required: false,
+    },
+    {
+      name: "logLevel",
+      type: "LogLevel | 'debug' | 'info' | 'warn' | 'error'",
+      description: "Logger level (default: 'info')",
+      required: false,
+    },
+  ]}
+/>
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to PostHog.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending batched events and shuts down the PostHog client.
+
+## Usage
+
+```typescript
+import { PosthogExporter } from "@mastra/posthog";
+
+const exporter = new PosthogExporter({
+  apiKey: process.env.POSTHOG_API_KEY!,
+  host: "https://us.i.posthog.com",
+  serverless: true,
+});
+```
+
+## Span Type Mapping
+
+| Mastra Span Type    | PostHog Event Type |
+| ------------------- | ------------------ |
+| `MODEL_GENERATION`  | `$ai_generation`   |
+| `MODEL_STEP`        | `$ai_generation`   |
+| `MODEL_CHUNK`       | `$ai_span`         |
+| `TOOL_CALL`         | `$ai_span`         |
+| `MCP_TOOL_CALL`     | `$ai_span`         |
+| `PROCESSOR_RUN`     | `$ai_span`         |
+| `AGENT_RUN`         | `$ai_span`         |
+| `WORKFLOW_RUN`      | `$ai_span`         |
+| All other workflows | `$ai_span`         |
+| `GENERIC`           | `$ai_span`         |

package/.docs/raw/reference/observability/tracing/instances.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Tracing | Observability | Mastra Docs"
+title: "Reference: Tracing | Observability"
 description: Core Tracing classes and methods
 asIndexPage: true
 ---
@@ -157,10 +157,6 @@ class CustomObservabilityInstance extends BaseObservabilityInstance {
 - [Interfaces Reference](/reference/v1/observability/tracing/interfaces) - Type definitions
 - [Spans Reference](/reference/v1/observability/tracing/spans) - Span lifecycle and methods
 
-### Examples
-
-- [Basic Tracing](/examples/v1/observability/basic-tracing) - Getting started example
-
 ### Exporters
 
 - [DefaultExporter](/reference/v1/observability/tracing/exporters/default-exporter) - Storage persistence

package/.docs/raw/reference/observability/tracing/interfaces.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Interfaces | Observability | Mastra Docs"
+title: "Reference: Interfaces | Observability"
 description: Tracing type definitions and interfaces
 ---
 
@@ -90,6 +90,9 @@ interface Span<TType extends SpanType> {
   output?: any;
   errorInfo?: any;
 
+  /** Tags for categorizing traces (only present on root spans) */
+  tags?: string[];
+
   /** End the span */
   end(options?: EndSpanOptions<TType>): void;
 
@@ -549,6 +552,32 @@ Options passed when starting a new agent or workflow execution.
 interface TracingOptions {
   /** Metadata to add to the root trace span */
   metadata?: Record<string, any>;
+
+  /**
+   * Additional RequestContext keys to extract as metadata for this trace.
+   * These keys are added to the requestContextKeys config.
+   * Supports dot notation for nested values (e.g., 'user.id', 'session.data.experimentId').
+   */
+  requestContextKeys?: string[];
+
+  /**
+   * Trace ID to use for this execution (1-32 hexadecimal characters).
+   * If provided, this trace will be part of the specified trace rather than starting a new one.
+   */
+  traceId?: string;
+
+  /**
+   * Parent span ID to use for this execution (1-16 hexadecimal characters).
+   * If provided, the root span will be created as a child of this span.
+   */
+  parentSpanId?: string;
+
+  /**
+   * Tags to apply to this trace.
+   * Tags are string labels that can be used to categorize and filter traces
+   * Note: Tags are only applied to the root span of a trace.
+   */
+  tags?: string[];
 }
 ```
 
@@ -707,7 +736,3 @@ enum InternalSpans {
 - [Configuration](/reference/v1/observability/tracing/configuration) - Registry and configuration
 - [Tracing Classes](/reference/v1/observability/tracing/instances) - Core implementations
 - [Spans Reference](/reference/v1/observability/tracing/spans) - Span lifecycle methods
-
-### Examples
-
-- [Basic Tracing](/examples/v1/observability/basic-tracing) - Implementation example

package/.docs/raw/reference/observability/tracing/processors/sensitive-data-filter.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: SensitiveDataFilter | Observability | Mastra Docs"
+title: "Reference: SensitiveDataFilter | Observability"
 description: API reference for the SensitiveDataFilter processor
 ---
 

package/.docs/raw/reference/observability/tracing/spans.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Spans | Observability | Mastra Docs"
+title: "Reference: Spans | Observability"
 description: Span interfaces, methods, and lifecycle events
 ---
 
@@ -386,7 +386,3 @@ A span that performs no operations. All methods are no-ops:
 - [Tracing Classes](/reference/v1/observability/tracing/instances) - Core tracing classes
 - [Interfaces](/reference/v1/observability/tracing/interfaces) - Complete type reference
 - [Configuration](/reference/v1/observability/tracing/configuration) - Configuration options
-
-### Examples
-
-- [Basic Tracing](/examples/v1/observability/basic-tracing) - Working with spans

package/.docs/raw/reference/processors/batch-parts-processor.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Batch Parts Processor | Processors | Mastra Docs"
+title: "Reference: Batch Parts Processor | Processors"
 description: "Documentation for the BatchPartsProcessor in Mastra, which batches multiple stream parts together to reduce frequency of emissions."
 ---
 
@@ -100,7 +100,7 @@ import { BatchPartsProcessor } from "@mastra/core/processors";
 export const agent = new Agent({
   name: "batched-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   outputProcessors: [
     new BatchPartsProcessor({
       batchSize: 5,

package/.docs/raw/reference/processors/language-detector.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Language Detector | Processors | Mastra Docs"
+title: "Reference: Language Detector | Processors"
 description: "Documentation for the LanguageDetector in Mastra, which detects language and can translate content in AI responses."
 ---
 
@@ -13,7 +13,7 @@ The `LanguageDetector` is an **input processor** that identifies the language of
 import { LanguageDetector } from "@mastra/core/processors";
 
 const processor = new LanguageDetector({
-  model: "openai/gpt-4.1-nano",
+  model: "openrouter/openai/gpt-oss-safeguard-20b",
   targetLanguages: ["English", "en"],
   threshold: 0.8,
   strategy: "translate"
@@ -99,6 +99,13 @@ const processor = new LanguageDetector({
       isOptional: true,
       default: "'quality'",
     },
+    {
+      name: "providerOptions",
+      type: "ProviderOptions",
+      description: "Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., `{ openai: { reasoningEffort: 'low' } }`)",
+      isOptional: true,
+      default: "undefined",
+    },
   ]}
 />
 
@@ -136,10 +143,10 @@ import { LanguageDetector } from "@mastra/core/processors";
 export const agent = new Agent({
   name: "multilingual-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   inputProcessors: [
     new LanguageDetector({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       targetLanguages: ["English", "en"],
       threshold: 0.8,
       strategy: "translate",

package/.docs/raw/reference/processors/message-history-processor.mdx

@@ -0,0 +1,131 @@
+---
+title: "Reference: Message History Processor | Processors"
+description: "Documentation for the MessageHistory processor in Mastra, which handles retrieval and persistence of conversation history."
+---
+
+# MessageHistory
+
+The `MessageHistory` is a **hybrid processor** that handles both retrieval and persistence of message history. On input, it fetches historical messages from storage and prepends them to the conversation. On output, it persists new messages to storage.
+
+## Usage example
+
+```typescript copy
+import { MessageHistory } from "@mastra/core/processors";
+
+const processor = new MessageHistory({
+  storage: memoryStorage,
+  lastMessages: 50,
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "MessageHistoryOptions",
+      description: "Configuration options for the message history processor",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "storage",
+      type: "MemoryStorage",
+      description: "Storage instance for retrieving and persisting messages",
+      isOptional: false,
+    },
+    {
+      name: "lastMessages",
+      type: "number",
+      description: "Maximum number of historical messages to retrieve. If not specified, retrieves all messages",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Processor identifier set to 'message-history'",
+      isOptional: false,
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Processor display name set to 'MessageHistory'",
+      isOptional: false,
+    },
+    {
+      name: "processInput",
+      type: "(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>",
+      description: "Fetches historical messages from storage and adds them to the message list",
+      isOptional: false,
+    },
+    {
+      name: "processOutputResult",
+      type: "(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList>",
+      description: "Persists new messages (user input and assistant response) to storage, excluding system messages",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Extended usage example
+
+```typescript title="src/mastra/agents/memory-agent.ts" showLineNumbers copy
+import { Agent } from "@mastra/core/agent";
+import { MessageHistory } from "@mastra/core/processors";
+import { PostgresStorage } from "@mastra/pg";
+
+const storage = new PostgresStorage({
+  connectionString: process.env.DATABASE_URL,
+});
+
+export const agent = new Agent({
+  name: "memory-agent",
+  instructions: "You are a helpful assistant with conversation memory",
+  model: "openai:gpt-4o",
+  inputProcessors: [
+    new MessageHistory({
+      storage,
+      lastMessages: 100,
+    }),
+  ],
+  outputProcessors: [
+    new MessageHistory({
+      storage,
+    }),
+  ],
+});
+```
+
+## Behavior
+
+### Input processing
+1. Retrieves `threadId` from the request context
+2. Fetches historical messages from storage (ordered by creation date, descending)
+3. Filters out system messages (they should not be stored in the database)
+4. Merges historical messages with incoming messages, avoiding duplicates by ID
+5. Adds historical messages with `source: 'memory'` tag
+
+### Output processing
+1. Retrieves `threadId` from the request context
+2. Skips persistence if `readOnly` is set in memory config
+3. Filters out incomplete tool calls from messages
+4. Persists new user input and assistant response messages to storage
+5. Updates the thread's `updatedAt` timestamp
+
+## Related
+
+- [Guardrails](/docs/v1/agents/guardrails)

package/.docs/raw/reference/processors/moderation-processor.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Moderation Processor | Processors | Mastra Docs"
+title: "Reference: Moderation Processor | Processors"
 description: "Documentation for the ModerationProcessor in Mastra, which provides content moderation using LLM to detect inappropriate content across multiple categories."
 ---
 
@@ -13,7 +13,7 @@ The `ModerationProcessor` is a **hybrid processor** that can be used for both in
 import { ModerationProcessor } from "@mastra/core/processors";
 
 const processor = new ModerationProcessor({
-  model: "openai/gpt-4.1-nano",
+  model: "openrouter/openai/gpt-oss-safeguard-20b",
   threshold: 0.7,
   strategy: "block",
   categories: ["hate", "harassment", "violence"]
@@ -85,6 +85,13 @@ const processor = new ModerationProcessor({
       isOptional: true,
       default: "0 (no context window)",
     },
+    {
+      name: "providerOptions",
+      type: "ProviderOptions",
+      description: "Provider-specific options passed to the internal moderation agent. Use this to control model behavior like reasoning effort for thinking models (e.g., `{ openai: { reasoningEffort: 'low' } }`)",
+      isOptional: true,
+      default: "undefined",
+    },
   ]}
 />
 
@@ -130,10 +137,10 @@ import { ModerationProcessor } from "@mastra/core/processors";
 export const agent = new Agent({
   name: "moderated-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   inputProcessors: [
     new ModerationProcessor({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       categories: ["hate", "harassment", "violence"],
       threshold: 0.7,
       strategy: "block",
@@ -155,7 +162,7 @@ import { BatchPartsProcessor, ModerationProcessor } from "@mastra/core/processor
 export const agent = new Agent({
   name: "output-moderated-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   outputProcessors: [
     // Batch stream parts first to reduce LLM calls
     new BatchPartsProcessor({
@@ -163,7 +170,7 @@ export const agent = new Agent({
     }),
     // Then apply moderation on batched content
     new ModerationProcessor({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       strategy: "filter",
       chunkWindow: 1,
     }),