@mastra/mcp-docs-server 0.13.24 → 0.13.25-alpha.1

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

@@ -0,0 +1,274 @@
+---
+title: "Sensitive Data Filter | Processors | Observability | Mastra Docs"
+description: "Protect sensitive information in your AI traces with automatic data redaction"
+---
+
+import { Callout } from "nextra/components";
+
+# Sensitive Data Filter
+
+The Sensitive Data Filter is a span processor that automatically redacts sensitive information from your AI traces before they're exported. This ensures that passwords, API keys, tokens, and other confidential data never leave your application or get stored in observability platforms.
+
+## Default Configuration
+
+By default, the Sensitive Data Filter is automatically enabled when you use the standard Mastra configuration:
+
+```ts filename="src/mastra/index.ts" showLineNumbers copy
+export const mastra = new Mastra({
+  observability: {
+    default: { enabled: true }, // Automatically includes SensitiveDataFilter
+  },
+  storage: new LibSQLStore({
+    url: "file:./mastra.db",
+  }),
+});
+```
+
+With the default configuration, the filter automatically redacts these common sensitive field names:
+
+- `password`
+- `token`
+- `secret`
+- `key`
+- `apikey`
+- `auth`
+- `authorization`
+- `bearer`
+- `bearertoken`
+- `jwt`
+- `credential`
+- `clientsecret`
+- `privatekey`
+- `refresh`
+- `ssn`
+
+<Callout>
+Field matching is case-insensitive and normalizes separators. For example, `api-key`, `api_key`, and `Api Key` are all treated as `apikey`.
+</Callout>
+
+## How It Works
+
+The Sensitive Data Filter processes spans before they're sent to exporters, scanning through:
+
+- **Attributes** - Span metadata and properties
+- **Metadata** - Custom metadata attached to spans
+- **Input** - Data sent to agents, tools, and LLMs
+- **Output** - Responses and results
+- **Error Information** - Stack traces and error details
+
+When a sensitive field is detected, its value is replaced with `[REDACTED]` by default. The filter handles nested objects, arrays, and circular references safely.
+
+## Custom Configuration
+
+You can customize which fields are redacted and how redaction appears:
+
+```ts filename="src/mastra/index.ts" showLineNumbers copy
+import { SensitiveDataFilter, DefaultExporter } from '@mastra/core/ai-tracing';
+
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      production: {
+        serviceName: 'my-service',
+        exporters: [new DefaultExporter()],
+        processors: [
+          new SensitiveDataFilter({
+            // Add custom sensitive fields
+            sensitiveFields: [
+              // Default fields
+              'password', 'token', 'secret', 'key', 'apikey',
+              // Custom fields for your application
+              'creditCard', 'bankAccount', 'routingNumber',
+              'email', 'phoneNumber', 'dateOfBirth',
+            ],
+            // Custom redaction token
+            redactionToken: '***SENSITIVE***',
+            // Redaction style
+            redactionStyle: 'full', // or 'partial'
+          })
+        ],
+      },
+    },
+  },
+});
+```
+
+## Redaction Styles
+
+The filter supports two redaction styles:
+
+### Full Redaction (Default)
+
+Replaces the entire value with a fixed token:
+
+```json
+// Before
+{
+  "apiKey": "sk-abc123xyz789def456",
+  "userId": "user_12345"
+}
+
+// After
+{
+  "apiKey": "[REDACTED]",
+  "userId": "user_12345"
+}
+```
+
+### Partial Redaction
+
+Shows the first and last 3 characters, useful for debugging without exposing full values:
+
+```ts
+new SensitiveDataFilter({
+  redactionStyle: 'partial'
+})
+```
+
+```json
+// Before
+{
+  "apiKey": "sk-abc123xyz789def456",
+  "creditCard": "4111111111111111"
+}
+
+// After
+{
+  "apiKey": "sk-…456",
+  "creditCard": "411…111"
+}
+```
+
+Values shorter than 7 characters are fully redacted to prevent information leakage.
+
+## Field Matching Rules
+
+The filter uses intelligent field matching:
+
+1. **Case-Insensitive**: `APIKey`, `apikey`, and `ApiKey` are all matched
+2. **Separator-Agnostic**: `api-key`, `api_key`, and `apiKey` are treated identically
+3. **Exact Matching**: After normalization, fields must match exactly
+   - `token` matches `token`, `Token`, `TOKEN`
+   - `token` does NOT match `promptTokens` or `tokenCount`
+
+## Nested Object Handling
+
+The filter recursively processes nested structures:
+
+```json
+// Before
+{
+  "user": {
+    "id": "12345",
+    "credentials": {
+      "password": "SuperSecret123!",
+      "apiKey": "sk-production-key"
+    }
+  },
+  "config": {
+    "auth": {
+      "jwt": "eyJhbGciOiJIUzI1NiIs..."
+    }
+  }
+}
+
+// After
+{
+  "user": {
+    "id": "12345",
+    "credentials": {
+      "password": "[REDACTED]",
+      "apiKey": "[REDACTED]"
+    }
+  },
+  "config": {
+    "auth": {
+      "jwt": "[REDACTED]"
+    }
+  }
+}
+```
+
+## Performance Considerations
+
+The Sensitive Data Filter is designed to be lightweight and efficient:
+
+- **Synchronous Processing**: No async operations, minimal latency impact
+- **Circular Reference Handling**: Safely handles complex object graphs
+- **Error Recovery**: If filtering fails, the field is replaced with an error marker rather than crashing
+
+## Disabling the Filter
+
+If you need to disable sensitive data filtering (not recommended for production):
+
+```ts filename="src/mastra/index.ts" showLineNumbers copy
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      debug: {
+        serviceName: 'debug-service',
+        processors: [], // No processors, including no SensitiveDataFilter
+        exporters: [new DefaultExporter()],
+      },
+    },
+  },
+});
+```
+
+<Callout type="warning">
+Only disable sensitive data filtering in controlled environments. Never disable it when sending traces to external services or shared storage.
+</Callout>
+
+## Common Use Cases
+
+### Healthcare Applications
+
+```ts
+new SensitiveDataFilter({
+  sensitiveFields: [
+    // HIPAA-related fields
+    'ssn', 'socialSecurityNumber',
+    'medicalRecordNumber', 'mrn',
+    'healthInsuranceNumber',
+    'diagnosisCode', 'icd10',
+    'prescription', 'medication',
+  ]
+})
+```
+
+### Financial Services
+
+```ts
+new SensitiveDataFilter({
+  sensitiveFields: [
+    // PCI compliance fields
+    'creditCard', 'ccNumber', 'cardNumber',
+    'cvv', 'cvc', 'securityCode',
+    'expirationDate', 'expiry',
+    'bankAccount', 'accountNumber',
+    'routingNumber', 'iban', 'swift',
+  ]
+})
+```
+
+## Error Handling
+
+If the filter encounters an error while processing a field, it replaces the field with a safe error marker:
+
+```json
+{
+  "problematicField": {
+    "error": {
+      "processor": "sensitive-data-filter"
+    }
+  }
+}
+```
+
+This ensures that processing errors don't prevent traces from being exported or cause application crashes.
+
+## Related
+
+- [SensitiveDataFilter API](/reference/observability/ai-tracing/processors/sensitive-data-filter)
+- [Basic AI Tracing Example](/examples/observability/basic-ai-tracing) 
+

package/.docs/raw/observability/{tracing.mdx → otel-tracing.mdx}

@@ -1,11 +1,11 @@
 ---
-title: "Tracing | Mastra Observability Documentation"
+title: "OTEL Tracing | Mastra Observability Documentation"
 description: "Set up OpenTelemetry tracing for Mastra applications"
 ---
 
 import Image from "next/image";
 
-# Tracing
+# OTEL Tracing
 
 Mastra supports the OpenTelemetry Protocol (OTLP) for tracing and monitoring your application. When telemetry is enabled, Mastra automatically traces all core primitives including agent operations, LLM interactions, tool executions, integration calls, workflow runs, and database operations. Your telemetry data can then be exported to any OTEL collector.
 

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

@@ -0,0 +1,66 @@
+---
+title: "Overview | Observability | Mastra Docs"
+description: Monitor and debug applications with Mastra's Observability features.
+---
+
+import { Callout } from "nextra/components";
+
+# Observability Overview
+
+Mastra provides comprehensive observability features designed specifically for AI applications. Monitor LLM operations, trace agent decisions, and debug complex workflows with specialized tools that understand AI-specific patterns.
+
+## Key Features
+
+### Structured Logging
+Debug applications with contextual logging:
+- **Context propagation**: Automatic correlation with traces
+- **Configurable levels**: Filter by severity in development and production
+
+### AI Tracing
+Specialized tracing for AI operations that captures:
+- **LLM interactions**: Token usage, latency, prompts, and completions
+- **Agent execution**: Decision paths, tool calls, and memory operations
+- **Workflow steps**: Branching logic, parallel execution, and step outputs
+- **Automatic instrumentation**: Zero-configuration tracing with decorators
+
+### OTEL Tracing
+Traditional distributed tracing with OpenTelemetry:
+- **Standard OTLP protocol**: Compatible with existing observability infrastructure
+- **HTTP and database instrumentation**: Automatic spans for common operations
+- **Provider integrations**: Datadog, New Relic, Jaeger, and other OTLP collectors
+- **Distributed context**: W3C Trace Context propagation
+
+## Quick Start
+
+Configure Observability in your Mastra instance:
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { PinoLogger } from "@mastra/core";
+import { LibSqlStorage } from "@mastra/libsql";
+
+export const mastra = new Mastra({
+  // ... other config
+  logger: new PinoLogger(),
+  observability: {
+    default: { enabled: true }, // Enables AI Tracing
+  },
+  storage: new LibSQLStore({
+    url: "file:./mastra.db", // Storage is required for tracing
+  }),
+  telemetry: {
+    enabled: true, // Enables OTEL Tracing
+  }
+});
+```
+
+With this basic setup, you will see Traces and Logs in both the Playground 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 [AI Tracing](/docs/observability/ai-tracing.mdx) documentation.
+
+## What's Next?
+
+- **[Set up AI Tracing](/docs/observability/ai-tracing.mdx)**: Configure tracing for your application
+- **[Configure Logging](/docs/observability/logging.mdx)**: Add structured logging
+- **[View Examples](/examples/observability/basic-ai-tracing.mdx)**: See observability in action
+- **[API Reference](/reference/observability/ai-tracing/ai-tracing.mdx)**: Detailed configuration options

package/.docs/raw/reference/agents/generate.mdx

@@ -193,7 +193,7 @@ await agent.generate("message for agent");
       type: "TelemetrySettings",
       isOptional: true,
       description:
-        "Settings for telemetry collection during generation.",
+        "Settings for OTLP telemetry collection during generation (not AI tracing).",
       properties: [
         {
           parameters: [{
@@ -339,6 +339,38 @@ await agent.generate("message for agent");
       isOptional: true,
       description: "Runtime context for dependency injection and contextual information.",
     },
+    {
+      name: "tracingContext",
+      type: "TracingContext",
+      isOptional: true,
+      description: "AI tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.",
+      properties: [
+        {
+          parameters: [{
+            name: "currentSpan",
+            type: "AISpan",
+            isOptional: true,
+            description: "Current AI span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution."
+          }]
+        }
+      ]
+    },
+    {
+      name: "tracingOptions",
+      type: "TracingOptions",
+      isOptional: true,
+      description: "Options for AI tracing configuration.",
+      properties: [
+        {
+          parameters: [{
+            name: "metadata",
+            type: "Record<string, any>",
+            isOptional: true,
+            description: "Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags."
+          }]
+        }
+      ]
+    },
     {
       name: "maxTokens",
       type: "number",
@@ -430,6 +462,12 @@ await agent.generate("message for agent");
         }
       ]
     },
+    {
+      name: "traceId",
+      type: "string",
+      isOptional: true,
+      description: "The trace ID associated with this execution when AI tracing is enabled. Use this to correlate logs and debug execution flow.",
+    },
   ]}
 />
 

package/.docs/raw/reference/agents/generateVNext.mdx

@@ -105,6 +105,32 @@ const aiSdkResult = await agent.generateVNext("message for agent", {
       type: "TracingContext",
       isOptional: true,
       description: "AI tracing context for span hierarchy and metadata.",
+      properties: [
+        {
+          parameters: [{
+            name: "currentSpan",
+            type: "AISpan",
+            isOptional: true,
+            description: "Current AI span for creating child spans and adding metadata."
+          }]
+        }
+      ]
+    },
+    {
+      name: "tracingOptions",
+      type: "TracingOptions",
+      isOptional: true,
+      description: "Options for AI tracing configuration.",
+      properties: [
+        {
+          parameters: [{
+            name: "metadata",
+            type: "Record<string, any>",
+            isOptional: true,
+            description: "Metadata to add to the root trace span."
+          }]
+        }
+      ]
     },
     {
       name: "returnScorerData",
@@ -286,7 +312,7 @@ const aiSdkResult = await agent.generateVNext("message for agent", {
       name: "telemetry",
       type: "TelemetrySettings",
       isOptional: true,
-      description: "Telemetry collection settings for observability.",
+      description: "Settings for OTLP telemetry collection (not AI tracing).",
       properties: [
         {
           parameters: [{
@@ -518,7 +544,13 @@ const aiSdkResult = await agent.generateVNext("message for agent", {
     {
       name: "result",
       type: "Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>> | Awaited<ReturnType<AISDKV5OutputStream<Output>['getFullOutput']>>",
-      description: "Returns the full output of the generation process. When format is 'mastra' (default), returns MastraModelOutput result. When format is 'aisdk', returns AISDKV5OutputStream result for AI SDK v5 compatibility.",
+      description: "Returns the full output of the generation process. When format is 'mastra' (default), returns MastraModelOutput result with traceId property. When format is 'aisdk', returns AISDKV5OutputStream result for AI SDK v5 compatibility.",
+    },
+    {
+      name: "traceId",
+      type: "string",
+      isOptional: true,
+      description: "The trace ID associated with this execution when AI tracing is enabled. Available in the result object (result.traceId for Mastra format).",
     },
   ]}
 />

package/.docs/raw/reference/agents/network.mdx

@@ -107,14 +107,40 @@ await agent.network(`
       name: "tracingContext",
       type: "TracingContext",
       isOptional: true,
-      description: "AI tracing context for span hierarchy and metadata.",
+      description: "AI tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.",
+      properties: [
+        {
+          parameters: [{
+            name: "currentSpan",
+            type: "AISpan",
+            isOptional: true,
+            description: "Current AI span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution."
+          }]
+        }
+      ]
+    },
+    {
+      name: "tracingOptions",
+      type: "TracingOptions",
+      isOptional: true,
+      description: "Options for AI tracing configuration.",
+      properties: [
+        {
+          parameters: [{
+            name: "metadata",
+            type: "Record<string, any>",
+            isOptional: true,
+            description: "Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags."
+          }]
+        }
+      ]
     },
     {
       name: "telemetry",
       type: "TelemetrySettings",
       isOptional: true,
       description:
-        "Settings for telemetry collection during streaming.",
+        "Settings for OTLP telemetry collection during streaming (not AI tracing).",
       properties: [
         {
           parameters: [{
@@ -227,6 +253,12 @@ await agent.network(`
       isOptional: true,
       description: "Runtime context for dependency injection and contextual information.",
     },
+    {
+      name: "traceId",
+      type: "string",
+      isOptional: true,
+      description: "The trace ID associated with this execution when AI tracing is enabled. Use this to correlate logs and debug execution flow.",
+    },
   ]}
 />
 
@@ -255,4 +287,4 @@ await agent.network(`
       description: "A promise that resolves to token usage statistics",
     },
   ]}
-/>
+/>

package/.docs/raw/reference/auth/clerk.mdx

@@ -11,7 +11,7 @@ The `MastraAuthClerk` class provides authentication for Mastra applications usin
 
 ```typescript filename="src/mastra/index.ts" showLineNumbers copy
 import { Mastra } from "@mastra/core/mastra";
-import { MastraAuthClerk } from '@mastra/clerk-auth';
+import { MastraAuthClerk } from '@mastra/auth-clerk';
 
 export const mastra = new Mastra({
   // ..

package/.docs/raw/reference/client-js/agents.mdx

@@ -165,26 +165,17 @@ const liveEvals = await agent.liveEvals();
 
 <StreamVNextCallout />
 
-Stream responses using the enhanced VNext API with improved method signatures. This method provides enhanced capabilities and format flexibility, with support for both Mastra's native format and AI SDK v5 compatibility:
+Stream responses using the enhanced VNext API with improved method signatures.
 
 ```typescript
 const response = await agent.streamVNext(
   "Tell me a story",
   {
-    format: 'mastra', // Default: Mastra's native format
     threadId: "thread-1",
     clientTools: { colorChangeTool },
   }
 );
 
-// AI SDK v5 compatible format
-const response = await agent.streamVNext(
-  "Tell me a story",
-  {
-    format: 'aisdk', // Enable AI SDK v5 compatibility
-    threadId: "thread-1",
-  }
-);
 
 // Process the stream
 response.processDataStream({
@@ -194,9 +185,9 @@ response.processDataStream({
 });
 ```
 
-The `format` parameter determines the output stream format:
-- `'mastra'` (default): Returns Mastra's native format
-- `'aisdk'`: Returns AI SDK v5 compatible format for frontend integration
+Currently, AI SDK V5 format is not supported in the client SDK.
+For AI SDK v5 compatible format, leverage the `@mastra/ai-sdk` package
+[AI SDK v5 Stream Compatibility](/docs/frameworks/agentic-uis/ai-sdk#enabling-stream-compatibility)
 
 ### Generate VNext (Experimental)
 

package/.docs/raw/reference/client-js/mastra-client.mdx

@@ -142,6 +142,16 @@ export const mastraClient = new MastraClient({
       type: "string[]",
       description: "Returns the list of configured log transport types.",
     },
+    {
+      name: "getAITrace(traceId)",
+      type: "Promise<AITraceRecord>",
+      description: "Retrieves a specific AI trace by ID, including all its spans and details.",
+    },
+    {
+      name: "getAITraces(params)",
+      type: "Promise<GetAITracesResponse>",
+      description: "Retrieves paginated list of AI trace root spans with optional filtering. Use getAITrace() to get complete traces with all spans.",
+    },
   ]}
 />
 

package/.docs/raw/reference/client-js/observability.mdx

@@ -0,0 +1,76 @@
+---
+title: Mastra Client Observability API
+description: Learn how to retrieve AI traces, monitor application performance, and score traces using the client-js SDK.
+---
+
+# Observability API
+
+The Observability API provides methods to retrieve AI traces, monitor your application's performance, and score traces for evaluation. This helps you understand how your AI agents and workflows are performing.
+
+## Getting a Specific AI Trace
+
+Retrieve a specific AI trace by its ID, including all its spans and details:
+
+```typescript
+const trace = await mastraClient.getAITrace("trace-id-123");
+```
+
+## Getting AI Traces with Filtering
+
+Retrieve a paginated list of AI trace root spans with optional filtering:
+
+```typescript
+const traces = await mastraClient.getAITraces({
+  pagination: {
+    page: 1,
+    perPage: 20,
+    dateRange: {
+      start: new Date('2024-01-01'),
+      end: new Date('2024-01-31')
+    }
+  },
+  filters: {
+    name: "weather-agent", // Filter by trace name
+    spanType: "agent", // Filter by span type
+    entityId: "weather-agent-id", // Filter by entity ID
+    entityType: "agent" // Filter by entity type
+  }
+});
+
+console.log(`Found ${traces.spans.length} root spans`);
+console.log(`Total pages: ${traces.pagination.totalPages}`);
+
+// To get the complete trace with all spans, use getAITrace
+const completeTrace = await mastraClient.getAITrace(traces.spans[0].traceId);
+```
+
+## Scoring Traces
+
+Score specific traces using registered scorers for evaluation:
+
+```typescript
+const result = await mastraClient.score({
+  scorerName: "answer-relevancy",
+  targets: [
+    { traceId: "trace-1", spanId: "span-1" }, // Score specific span
+    { traceId: "trace-2" }, // Score specific span which defaults to the parent span
+  ]
+});
+```
+
+## Getting Scores by Span
+
+Retrieve scores for a specific span within a trace:
+
+```typescript
+const scores = await mastraClient.getScoresBySpan({
+  traceId: "trace-123",
+  spanId: "span-456",
+  page: 1,
+  perPage: 20
+});
+```
+## Related
+
+- [Agents API](./agents) - Learn about agent interactions that generate traces
+- [Workflows API](./workflows) - Understand workflow execution monitoring