@mastra/mcp-docs-server 0.13.7 → 0.13.8-alpha.0

package/.docs/organized/changelogs/mastra.md

@@ -1,5 +1,74 @@
 # mastra
 
+## 0.10.17-alpha.0
+
+### Patch Changes
+
+- 33dcb07: dependencies updates:
+  - Updated dependency [`@opentelemetry/instrumentation@^0.203.0` ↗︎](https://www.npmjs.com/package/@opentelemetry/instrumentation/v/0.203.0) (from `^0.202.0`, in `dependencies`)
+  - Updated dependency [`@opentelemetry/auto-instrumentations-node@^0.62.0` ↗︎](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node/v/0.62.0) (from `^0.60.1`, in `dependencies`)
+  - Updated dependency [`@opentelemetry/exporter-trace-otlp-grpc@^0.203.0` ↗︎](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-grpc/v/0.203.0) (from `^0.202.0`, in `dependencies`)
+  - Updated dependency [`@opentelemetry/exporter-trace-otlp-http@^0.203.0` ↗︎](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-http/v/0.203.0) (from `^0.202.0`, in `dependencies`)
+  - Updated dependency [`@opentelemetry/sdk-node@^0.203.0` ↗︎](https://www.npmjs.com/package/@opentelemetry/sdk-node/v/0.203.0) (from `^0.202.0`, in `dependencies`)
+  - Updated dependency [`@opentelemetry/semantic-conventions@^1.36.0` ↗︎](https://www.npmjs.com/package/@opentelemetry/semantic-conventions/v/1.36.0) (from `^1.34.0`, in `dependencies`)
+- Updated dependencies [33dcb07]
+- Updated dependencies [f90797b]
+- Updated dependencies [d30b1a0]
+- Updated dependencies [bff87f7]
+- Updated dependencies [07fe7a2]
+- Updated dependencies [b4a8df0]
+  - @mastra/core@0.12.1-alpha.0
+  - @mastra/mcp@0.10.9-alpha.0
+  - @mastra/deployer@0.12.1-alpha.0
+
+## 0.10.16
+
+### Patch Changes
+
+- bc6b44a: Extract tools import from `createHonoServer`; the function now receives tools via a prop on the `options` parameter.
+- f442224: speech to text using voice config
+- 7a7754f: Fast follow scorers fixing input types, improve llm scorer reliability, fix ui to display scores that are 0
+- d8dec5e: add a cta to invite to deploy to cloud
+- 6336993: Fix workflow input form overflow
+- d5cc460: This change implements a fix to sourcemap mappings being off due to `removeDeployer` Babel plugin missing source map config.
+- f42c4c2: update peer deps for packages to latest core range
+- a5681f2: fix: pagination breaks trace grouping
+- 89d2f4e: add TTS to the playground
+- Updated dependencies [510e2c8]
+- Updated dependencies [2f72fb2]
+- Updated dependencies [27cc97a]
+- Updated dependencies [832691b]
+- Updated dependencies [557bb9d]
+- Updated dependencies [27cc97a]
+- Updated dependencies [3f89307]
+- Updated dependencies [9eda7d4]
+- Updated dependencies [9d49408]
+- Updated dependencies [bc6b44a]
+- Updated dependencies [41daa63]
+- Updated dependencies [ad0a58b]
+- Updated dependencies [254a36b]
+- Updated dependencies [2ecf658]
+- Updated dependencies [7a7754f]
+- Updated dependencies [fc92d80]
+- Updated dependencies [e0f73c6]
+- Updated dependencies [0b89602]
+- Updated dependencies [4d37822]
+- Updated dependencies [23a6a7c]
+- Updated dependencies [cda801d]
+- Updated dependencies [a77c823]
+- Updated dependencies [ff9c125]
+- Updated dependencies [09bca64]
+- Updated dependencies [9802f42]
+- Updated dependencies [d5cc460]
+- Updated dependencies [f42c4c2]
+- Updated dependencies [b8efbb9]
+- Updated dependencies [71466e7]
+- Updated dependencies [0c99fbe]
+  - @mastra/core@0.12.0
+  - @mastra/deployer@0.12.0
+  - @mastra/loggers@0.10.5
+  - @mastra/mcp@0.10.8
+
 ## 0.10.16-alpha.3
 
 ### Patch Changes
@@ -229,74 +298,5 @@
 - f9b1508: add the same agent table as in cloud and export it from the playground
 - dfbeec6: Fix navigation to vnext AgentNetwork agents
 - Updated dependencies [7776324]
-- Updated dependencies [0b56518]
-- Updated dependencies [db5cc15]
-- Updated dependencies [2ba5b76]
-- Updated dependencies [7b57e2c]
-- Updated dependencies [5237998]
-- Updated dependencies [c3a30de]
-- Updated dependencies [37c1acd]
-- Updated dependencies [1aa60b1]
-- Updated dependencies [89ec9d4]
-- Updated dependencies [cf3a184]
-- Updated dependencies [fe4bbd4]
-- Updated dependencies [d6bfd60]
-- Updated dependencies [626b0f4]
-- Updated dependencies [c22a91f]
-- Updated dependencies [f7403ab]
-- Updated dependencies [6c89d7f]
-  - @mastra/deployer@0.10.15
-  - @mastra/core@0.10.15
-
-## 0.10.13-alpha.2
-
-### Patch Changes
-
-- 794d9f3: Fix thread creation in playground
-- dfbeec6: Fix navigation to vnext AgentNetwork agents
-
-## 0.10.13-alpha.1
-
-### Patch Changes
-
-- d49334d: export tool list for usage in cloud
-- 9cdfcb5: fix infinite rerenders on agents table + share runtime context for cloud
-- 45174f3: share network list between core and cloud
-- 48f5532: export workflow list for usage in cloud
-- 3e484be: Added CLI template option
-- Updated dependencies [0b56518]
-- Updated dependencies [2ba5b76]
-- Updated dependencies [c3a30de]
-- Updated dependencies [cf3a184]
-- Updated dependencies [fe4bbd4]
-- Updated dependencies [d6bfd60]
-  - @mastra/core@0.10.15-alpha.1
-  - @mastra/deployer@0.10.15-alpha.1
 
-## 0.10.13-alpha.0
-
-### Patch Changes
-
-- 593631d: allow to pass ref to the link abstraction
-- 5237998: Fix foreach output
-- 1aa60b1: Pipe runtimeContext to vNext network agent stream and generate steps, wire up runtimeContext for vNext Networks in cliet SDK & playground
-- 5130bcb: dependencies updates:
-  - Updated dependency [`swr@^2.3.4` ↗︎](https://www.npmjs.com/package/swr/v/2.3.4) (from `^2.3.3`, in `dependencies`)
-- 984887a: dependencies updates:
-  - Updated dependency [`prettier@^3.6.2` ↗︎](https://www.npmjs.com/package/prettier/v/3.6.2) (from `^3.5.3`, in `dependencies`)
-- aa9528a: Display reasoning in playground
-- 626b0f4: [Cloud-126] Working Memory Playground - Added working memory to playground to allow users to view/edit working memory
-- e1d0080: abstract Link component between cloud and core
-- f9b1508: add the same agent table as in cloud and export it from the playground
-- Updated dependencies [7776324]
-- Updated dependencies [db5cc15]
-- Updated dependencies [7b57e2c]
-- Updated dependencies [5237998]
-- Updated dependencies [37c1acd]
-- Updated dependencies [1aa60b1]
-- Updated dependencies [89ec9d4]
-- Updated dependencies [626b0f4]
-- Updated dependencies [c22a91f]
-- Updated dependencies [f7403ab]
-
-... 4605 more lines hidden. See full changelog in package directory.
+... 4674 more lines hidden. See full changelog in package directory.

package/.docs/raw/community/contributing-templates.mdx

@@ -27,6 +27,7 @@ Create your template following the established patterns:
 - Include comprehensive documentation
 - Test thoroughly with fresh installations
 - Follow all technical requirements
+- Ensure the github repo is a template repo. [How to create a template repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository)
 
 ### 3. Submit for Review
 

package/.docs/raw/memory/overview.mdx

@@ -68,7 +68,7 @@ Send a few messages and notice that it remembers information across turns:
 
 Mastra organizes memory into threads, which are records that identify specific conversation histories, using two identifiers:
 
-1.  **`threadId`**: A specific conversation id (e.g., `support_123`).
+1.  **`threadId`**: A globally unique conversation id (e.g., `support_123`). Thread IDs must be unique across all resources.
 2.  **`resourceId`**: The user or entity id that owns each thread (e.g., `user_123`, `org_456`).
 
 The `resourceId` is particularly important for [resource-scoped working memory](./working-memory.mdx#resource-scoped-memory), which allows memory to persist across all conversation threads for the same user.
@@ -82,6 +82,8 @@ const response = await myMemoryAgent.stream("Hello, my name is Alice.", {
 
 **Important:** without these ID's your agent will not use memory, even if memory is properly configured. The playground handles this for you, but you need to add ID's yourself when using memory in your application.
 
+> **Thread ID Uniqueness:** Each thread ID must be globally unique across all resources. A thread is permanently associated with the resource that created it. If you need to have similar thread names for different resources (e.g., a "general" thread for multiple users), include the resource ID in the thread ID: `${resourceId}-general` or `user_alice_general`.
+
 ### Thread Title Generation
 
 Mastra can automatically generate meaningful titles for conversation threads based on the user's first message. This helps organize and identify conversations in your application UI.

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

@@ -298,6 +298,73 @@ again because it has been stored in working memory.
 If your agent is not properly updating working memory when you expect it to, you can add system
 instructions on _how_ and _when_ to use this template in your agent's `instructions` setting.
 
+## Setting Initial Working Memory
+
+While agents typically update working memory through the `updateWorkingMemory` tool, you can also set initial working memory programmatically when creating or updating threads. This is useful for injecting user data (like their name, preferences, or other info) that you want available to the agent without passing it in every request.
+
+### Setting Working Memory via Thread Metadata
+
+When creating a thread, you can provide initial working memory through the metadata's `workingMemory` key:
+
+```typescript filename="src/app/medical-consultation.ts" showLineNumbers copy
+// Create a thread with initial working memory
+const thread = await memory.createThread({
+  threadId: "thread-123",
+  resourceId: "user-456",
+  title: "Medical Consultation",
+  metadata: {
+    workingMemory: `# Patient Profile
+- Name: John Doe
+- Blood Type: O+
+- Allergies: Penicillin
+- Current Medications: None
+- Medical History: Hypertension (controlled)
+`
+  }
+});
+
+// The agent will now have access to this information in all messages
+await agent.generate("What's my blood type?", {
+  threadId: thread.id,
+  resourceId: "user-456"
+});
+// Response: "Your blood type is O+."
+```
+
+### Updating Working Memory Programmatically
+
+You can also update an existing thread's working memory:
+
+```typescript filename="src/app/medical-consultation.ts" showLineNumbers copy
+// Update thread metadata to add/modify working memory
+await memory.updateThread({
+  id: "thread-123",
+  title: thread.title,
+  metadata: {
+    ...thread.metadata,
+    workingMemory: `# Patient Profile
+- Name: John Doe
+- Blood Type: O+
+- Allergies: Penicillin, Ibuprofen  // Updated
+- Current Medications: Lisinopril 10mg daily  // Added
+- Medical History: Hypertension (controlled)
+`
+  }
+});
+```
+
+### Direct Memory Update
+
+Alternatively, use the `updateWorkingMemory` method directly:
+
+```typescript filename="src/app/medical-consultation.ts" showLineNumbers copy
+await memory.updateWorkingMemory({
+  threadId: "thread-123",
+  resourceId: "user-456", // Required for resource-scoped memory
+  workingMemory: "Updated memory content..."
+});
+```
+
 ## Examples
 
 - [Streaming working memory](/examples/memory/streaming-working-memory)

package/.docs/raw/observability/logging.mdx

@@ -1,38 +1,113 @@
 ---
 title: "Logging | Mastra Observability Documentation"
-description: Documentation on effective logging in Mastra, crucial for understanding application behavior and improving AI accuracy.
+description: Learn how to use logging in Mastra to monitor execution, capture application behavior, and improve the accuracy of AI applications.
 ---
 
-import Image from "next/image";
-
 # Logging
 
-In Mastra, logs can detail when certain functions run, what input data they receive, and how they respond.
+Mastra's logging system captures function execution, input data, and output responses in a structured format.
+
+When deploying to Mastra Cloud, logs are shown on the [Logs](../mastra-cloud/observability.mdx) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
-## Basic Setup
+## PinoLogger
 
-Here's a minimal example that sets up a **console logger** at the `INFO` level. This will print out informational messages and above (i.e., `DEBUG`, `INFO`, `WARN`, `ERROR`) to the console.
+When [initializing a new Mastra project](../getting-started/installation.mdx) using the CLI, `PinoLogger` is included by default.
 
-```typescript filename="mastra.config.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core";
-import { PinoLogger } from "@mastra/loggers";
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from '@mastra/core/mastra';
+import { PinoLogger } from '@mastra/loggers';
 
 export const mastra = new Mastra({
-  // Other Mastra configuration...
+  // ...
   logger: new PinoLogger({
-    name: "Mastra",
-    level: "info",
+    name: 'Mastra',
+    level: 'info',
   }),
 });
 ```
 
-In this configuration:
+> See the [PinoLogger](../../reference/observability/logger.mdx) API reference for all available configuration options.
+
+## Logging from workflows and tools
+
+Mastra provides access to a logger instance via the `mastra.getLogger()` method, available inside both workflow steps and tools. The logger supports standard severity levels: `debug`, `info`, `warn`, and `error`.
+
+### Logging from workflow steps
+
+Within a workflow step, access the logger via the `mastra` parameter inside the `execute` function. This allows you to log messages relevant to the step’s execution.
+
+
+```typescript {8-9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  //...
+  execute: async ({ mastra }) => {
+
+    const logger = mastra.getLogger();
+    logger.info("workflow info log");
+
+    return {
+      output: ""
+    };
+  }
+});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .commit();
+```
+
+### Logging from tools
+
+Similarly, tools have access to the logger instance via the `mastra` parameter. Use this to log tool specific activity during execution.
 
-- `name: "Mastra"` specifies the name to group logs under.
-- `level: "info"` sets the minimum severity of logs to record.
+```typescript {8-9} filename="src/mastra/tools/test-tool.ts" showLineNumbers copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
 
-## Configuration
+export const testTool = createTool({
+  // ...
+  execute: async ({ mastra }) => {
 
-- For more details on the options you can pass to `PinoLogger()`, see the [PinoLogger reference documentation](/reference/observability/logger).
-- Once you have a `Logger` instance, you can call its methods (e.g., `.info()`, `.warn()`, `.error()`) in the [Logger instance reference documentation](/reference/observability/logger).
-- If you want to send your logs to an external service for centralized collection, analysis, or storage, you can configure other logger types such as Upstash Redis. Consult the [Logger reference documentation](/reference/observability/logger) for details on parameters like `url`, `token`, and `key` when using the `UPSTASH` logger type.
+    const logger = mastra?.getLogger();
+    logger?.info("tool info log");
+
+    return {
+      output: ""
+    };
+  }
+});
+```
+
+
+## Logging with additional data
+
+Logger methods accept an optional second argument for additional data. This can be any value, such as an object, string, or number.
+
+In this example, the log message includes an object with a key of `agent` and a value of the `testAgent` instance.
+
+```typescript {11} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  //...
+  execute: async ({ mastra }) => {
+
+    const testAgent = mastra.getAgent("testAgent");
+
+    const logger = mastra.getLogger();
+    logger.info("workflow info log", { agent: testAgent });
+
+    return {
+      output: ""
+    };
+  }
+});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .commit();
+```

package/.docs/raw/reference/observability/logger.mdx

@@ -1,86 +1,98 @@
 ---
-title: "Reference: Logger Instance | Mastra Observability Docs"
-description: Documentation for Logger instances, which provide methods to record events at various severity levels.
+title: "Reference: PinoLogger | Mastra Observability Docs"
+description: Documentation for PinoLogger, which provides methods to record events at various severity levels.
 ---
 
-# Logger Instance
+# PinoLogger
 
-A Logger instance is created by `new PinoLogger()` and provides methods to record events at various severity levels. Depending on the logger type, messages may be written to the console, file, or an external service.
+A Logger instance is created using `new PinoLogger()` and provides methods to record events at various severity levels.
 
-## Example
+When deploying to Mastra Cloud, logs are displayed on the [Logs](../../docs/mastra-cloud/dashboard.mdx#logs) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
-```typescript showLineNumbers copy
-// Using a console logger
-const logger = new PinoLogger({ name: "Mastra", level: "info" });
+## Usage example
 
-logger.debug("Debug message"); // Won't be logged because level is INFO
-logger.info({
-  message: "User action occurred",
-  destinationPath: "user-actions",
-  type: "AGENT",
-}); // Logged
-logger.error("An error occurred"); // Logged as ERROR
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from '@mastra/core/mastra';
+import { PinoLogger } from '@mastra/loggers';
+
+export const mastra = new Mastra({
+  // ...
+  logger: new PinoLogger({
+    name: 'Mastra',
+    level: 'info',
+  }),
+});
 ```
 
-## Methods
+## Parameters
 
 <PropertiesTable
   content={[
     {
-      name: "debug",
-      type: "(message: BaseLogMessage | string, ...args: any[]) => void | Promise<void>",
-      description: "Write a DEBUG-level log. Only recorded if level ≤ DEBUG.",
+      name: "name",
+      type: "string",
+      description: "A label used to group and identify logs from this logger.",
     },
-    {
-      name: "info",
-      type: "(message: BaseLogMessage | string, ...args: any[]) => void | Promise<void>",
-      description: "Write an INFO-level log. Only recorded if level ≤ INFO.",
+     {
+      name: "level",
+      type: `"debug" | "info" | "warn" | "error"`,
+      description: "Sets the minimum log level. Messages below this level are ignored.",
     },
     {
-      name: "warn",
-      type: "(message: BaseLogMessage | string, ...args: any[]) => void | Promise<void>",
-      description: "Write a WARN-level log. Only recorded if level ≤ WARN.",
+      name: "transports",
+      type: "Record<string, LoggerTransport>",
+      description: "A map of transport instances used to persist logs.",
     },
     {
-      name: "error",
-      type: "(message: BaseLogMessage | string, ...args: any[]) => void | Promise<void>",
-      description: "Write an ERROR-level log. Only recorded if level ≤ ERROR.",
+      name: "overrideDefaultTransports",
+      type: "boolean",
+      isOptional: true,
+      description: "If true, disables the default console transport.",
     },
     {
-      name: "cleanup",
-      type: "() => Promise<void>",
+      name: "formatters",
+      type: "pino.LoggerOptions['formatters']",
       isOptional: true,
-      description:
-        "Cleanup resources held by the logger (e.g., network connections for Upstash). Not all loggers implement this.",
+      description: "Custom Pino formatters for log serialization.",
     },
   ]}
 />
 
-**Note:** Some loggers require a `BaseLogMessage` object (with `message`, `destinationPath`, `type` fields). For instance, the `File` and `Upstash` loggers need structured messages.
 
-## File Transport (Structured Logs)
+## File transport (structured logs)
 
-```typescript showLineNumbers copy
+Writes structured logs to a file using the `FileTransport`. The logger accepts a plain message as the first argument and structured metadata as the second argument. These are internally converted to a `BaseLogMessage` and persisted to the configured file path.
+
+
+```typescript filename="src/mastra/loggers/file-transport.ts" showLineNumbers copy
 import { FileTransport } from "@mastra/loggers/file";
+import { PinoLogger } from "@mastra/loggers/pino";
 
-const fileLogger = new PinoLogger({
+export const fileLogger = new PinoLogger({
   name: "Mastra",
   transports: { file: new FileTransport({ path: "test-dir/test.log" }) },
   level: "warn",
 });
+```
+
+### File transport usage
 
+```typescript showLineNumbers copy
 fileLogger.warn("Low disk space", {
   destinationPath: "system",
   type: "WORKFLOW",
 });
 ```
 
-## Upstash Logger (Remote Log Drain)
+## Upstash transport (remote log drain)
 
-```typescript showLineNumbers copy
+Streams structured logs to a remote Redis list using the `UpstashTransport`. The logger accepts a string message and a structured metadata object. This enables centralized logging for distributed environments, supporting filtering by `destinationPath`, `type`, and `runId`.
+
+```typescript filename="src/mastra/loggers/upstash-transport.ts" showLineNumbers copy
 import { UpstashTransport } from "@mastra/loggers/upstash";
+import { PinoLogger } from "@mastra/loggers/pino";
 
-const logger = new PinoLogger({
+export const upstashLogger = new PinoLogger({
   name: "Mastra",
   transports: {
     upstash: new UpstashTransport({
@@ -91,28 +103,35 @@ const logger = new PinoLogger({
   },
   level: "info",
 });
+```
 
-logger.info({
-  message: "User signed in",
+
+### Upstash transport usage
+
+```typescript showLineNumbers copy
+upstashLogger.info("User signed in", {
   destinationPath: "auth",
   type: "AGENT",
   runId: "run_123",
 });
 ```
 
-## Custom Transport
+## Custom transport
 
 You can create custom transports using the `createCustomTransport` utility to integrate with any logging service or stream.
 
-### Example: Sentry Integration
+### Sentry transport example
 
-```typescript showLineNumbers copy
+Creates a custom transport using `createCustomTransport` and integrates it with a third-party logging stream such as `pino-sentry-transport`. This allows forwarding logs to an external system like Sentry for advanced monitoring and observability.
+
+```typescript filename="src/mastra/loggers/sentry-transport.ts" showLineNumbers copy
 import { createCustomTransport } from "@mastra/core/loggers";
-import pinoSentry from 'pino-sentry-transport';
+import { PinoLogger } from "@mastra/loggers/pino";
+import pinoSentry from "pino-sentry-transport";
 
 const sentryStream = await pinoSentry({
   sentry: {
-    dsn: 'YOUR_SENTRY_DSN',
+    dsn: "YOUR_SENTRY_DSN",
     _experiments: {
       enableLogs: true,
     },
@@ -121,9 +140,9 @@ const sentryStream = await pinoSentry({
 
 const customTransport = createCustomTransport(sentryStream);
 
-const logger = new PinoLogger({
+export const sentryLogger = new PinoLogger({
   name: "Mastra",
-  transports: { sentry: customTransport },
   level: "info",
+  transports: { sentry: customTransport },
 });
-```
+```

package/.docs/raw/reference/observability/providers/langfuse.mdx

@@ -11,36 +11,69 @@ Langfuse is an open-source observability platform designed specifically for LLM
 
 ## Configuration
 
-To use Langfuse with Mastra, you'll need to configure the following environment variables:
+To use Langfuse with Mastra, you can configure it using either environment variables or directly in your Mastra configuration.
+
+### Using Environment Variables
+
+Set the following environment variables:
 
 ```env
-LANGFUSE_PUBLIC_KEY=your_public_key
-LANGFUSE_SECRET_KEY=your_secret_key
-LANGFUSE_BASEURL=https://cloud.langfuse.com  # Optional - defaults to cloud.langfuse.com
+OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel/v1/traces" # 🇪🇺 EU data region
+# OTEL_EXPORTER_OTLP_ENDPOINT="https://us.cloud.langfuse.com/api/public/otel/v1/traces" # 🇺🇸 US data region
+
+OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${AUTH_STRING}"
+```
+
+Where `AUTH_STRING` is the base64-encoded combination of your public and secret keys (see below).
+
+### Generating AUTH_STRING
+
+The authorization uses basic auth with your Langfuse API keys. You can generate the base64-encoded auth string using:
+
+```bash
+echo -n "pk-lf-1234567890:sk-lf-1234567890" | base64
 ```
 
-**Important**: When configuring the telemetry export settings, the `traceName` parameter must be set to `"ai"` for the Langfuse integration to work properly.
+For long API keys on GNU systems, you may need to add `-w 0` to prevent auto-wrapping:
+
+```bash
+echo -n "pk-lf-1234567890:sk-lf-1234567890" | base64 -w 0
+```
 
 ## Implementation
 
-Here's how to configure Mastra to use Langfuse:
+Here's how to configure Mastra to use Langfuse with OpenTelemetry:
+
+```typescript
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  // ... other config
+  telemetry: {
+    enabled: true,
+    export: {
+      type: 'otlp',
+      endpoint: 'https://cloud.langfuse.com/api/public/otel/v1/traces', // or your preferred endpoint
+      headers: {
+        Authorization: `Basic ${AUTH_STRING}`, // Your base64-encoded auth string
+      },
+    },
+  },
+});
+```
+
+Alternatively, if you're using environment variables, you can simplify the configuration:
 
 ```typescript
 import { Mastra } from "@mastra/core";
-import { LangfuseExporter } from "langfuse-vercel";
 
 export const mastra = new Mastra({
   // ... other config
   telemetry: {
-    serviceName: "ai", // this must be set to "ai" so that the LangfuseExporter thinks it's an AI SDK trace
     enabled: true,
     export: {
-      type: "custom",
-      exporter: new LangfuseExporter({
-        publicKey: process.env.LANGFUSE_PUBLIC_KEY,
-        secretKey: process.env.LANGFUSE_SECRET_KEY,
-        baseUrl: process.env.LANGFUSE_BASEURL,
-      }),
+      type: 'otlp',
+      // endpoint and headers will be read from OTEL_EXPORTER_OTLP_* env vars
     },
   },
 });