@mastra/mcp-docs-server 1.2.8-alpha.0 → 1.2.8-alpha.19

package/.docs/docs/mastra-platform/workspace.md

@@ -0,0 +1,111 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workspace
+
+A workspace gives an environment two things your agents can use at runtime:
+
+- A **bucket** for filesystem storage, exposed to your code as [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem).
+- A **sandbox** for executing commands, exposed as [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox).
+
+Workspaces are provisioned per [environment](https://mastra.ai/docs/mastra-platform/environments), so `production` and `staging` each get their own bucket and sandbox. The platform manages provisioning, credentials, and lifecycle; your deploy code only needs to construct the providers.
+
+## When workspaces are provisioned
+
+New projects have workspaces enabled by default. When you create an environment, the platform provisions a bucket for it automatically. The sandbox base image is warmed in the background so the first `PlatformSandbox` call starts quickly.
+
+Existing projects that haven't opted in show an **Enable workspaces** action in the Workspaces tab. Enabling provisions a bucket for every environment on the project.
+
+If provisioning fails for an environment — for example while Railway is under load — the Workspaces tab shows the failure and offers a retry. The environment itself is still created; only the workspace is unavailable until you retry.
+
+## Use the workspace from your code
+
+Install the provider package:
+
+**npm**:
+
+```bash
+npm install @mastra/platform-workspace
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/platform-workspace
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/platform-workspace
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/platform-workspace
+```
+
+Compose the providers into a workspace and register it with Mastra:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'
+
+export const workspace = new Workspace({
+  filesystem: new PlatformFilesystem(),
+  sandbox: new PlatformSandbox(),
+})
+```
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { workspace } from './workspace'
+
+export const mastra = new Mastra({
+  workspace,
+})
+```
+
+`PlatformFilesystem` and `PlatformSandbox` read their credentials from environment variables the platform injects at deploy time, so you don't pass any options on the platform.
+
+## Injected environment variables
+
+Every deploy that runs on a platform environment with a workspace receives these variables:
+
+| Variable                       | Contents                                                                                             |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `MASTRA_PLATFORM_ACCESS_TOKEN` | Access token scoped to the deploy. Used by the workspace providers to authenticate.                  |
+| `MASTRA_PROJECT_ID`            | Project the deploy belongs to.                                                                       |
+| `MASTRA_ENVIRONMENT_ID`        | Environment the deploy belongs to. Selects which sandbox pool the platform uses.                     |
+| `MASTRA_PLATFORM_BUCKET_NAME`  | Bucket name attached to the environment. Selects which bucket `PlatformFilesystem` reads and writes. |
+
+These names are reserved. If your project sets any of them explicitly, the platform-managed values take precedence.
+
+## Local development
+
+Reuse the same providers locally by putting the four variables in your `.env` file. Get the values from your project's Workspaces tab:
+
+```bash
+MASTRA_PLATFORM_ACCESS_TOKEN=your-access-token
+MASTRA_PROJECT_ID=your-project-id
+MASTRA_ENVIRONMENT_ID=your-environment-id
+MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
+```
+
+`PlatformFilesystem` and `PlatformSandbox` behave the same locally as on the platform — they connect to the same bucket and sandbox pool for that environment. Use a `staging` or `preview` environment's variables for local runs if you want to keep production data isolated.
+
+For a purely offline loop that never touches the platform, swap the providers for [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) in a local build.
+
+## Inspect the workspace
+
+The Workspaces tab in your platform project shows, per environment:
+
+- Bucket status and its contents, with upload, download, and delete actions.
+- Recent sandbox sessions with their command, exit code, and duration.
+- Provisioning failures with a **Retry** action.
+
+## See also
+
+- [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem) — reference for the filesystem provider.
+- [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox) — reference for the sandbox provider.
+- [Environments](https://mastra.ai/docs/mastra-platform/environments) — how environments scope workspaces, variables, and databases.

package/.docs/docs/mcp/overview.md

@@ -64,7 +64,7 @@ export const testMcpClient = new MCPClient({
 
 Visit [MCPClient](https://mastra.ai/reference/tools/mcp-client) for a full list of configuration options.
 
-> **Authentication:** For connecting to OAuth-protected MCP servers, see the [OAuth Authentication](https://mastra.ai/reference/tools/mcp-client) section.
+> **Authentication:** For connecting to OAuth-protected MCP servers — including completing the browser-based authorization flow with `authenticate()` — see the [OAuth Authentication](https://mastra.ai/reference/tools/mcp-client) section.
 
 ## Using `MCPClient` with an agent
 

package/.docs/docs/memory/multi-user-threads.md

@@ -58,7 +58,7 @@ import { Memory } from '@mastra/memory'
 import { LibSQLStore } from '@mastra/libsql'
 
 const memory = new Memory({
-  storage: new LibSQLStore({ url: 'file:./collab.db' }),
+  storage: new LibSQLStore({ id: 'collab-storage', url: 'file:./collab.db' }),
   options: {
     lastMessages: 20,
   },
@@ -128,7 +128,7 @@ import { Memory } from '@mastra/memory'
 import { LibSQLStore } from '@mastra/libsql'
 
 const memory = new Memory({
-  storage: new LibSQLStore({ url: 'file:./collab.db' }),
+  storage: new LibSQLStore({ id: 'collab-storage', url: 'file:./collab.db' }),
   options: {
     lastMessages: 20,
   },
@@ -148,7 +148,7 @@ import { Memory } from '@mastra/memory'
 import { LibSQLStore } from '@mastra/libsql'
 
 const memory = new Memory({
-  storage: new LibSQLStore({ url: 'file:./collab.db' }),
+  storage: new LibSQLStore({ id: 'collab-storage', url: 'file:./collab.db' }),
   options: {
     lastMessages: 20,
     observationalMemory: true,
@@ -171,7 +171,7 @@ import { Memory } from '@mastra/memory'
 import { LibSQLStore } from '@mastra/libsql'
 
 const memory = new Memory({
-  storage: new LibSQLStore({ url: 'file:./collab.db' }),
+  storage: new LibSQLStore({ id: 'collab-storage', url: 'file:./collab.db' }),
   options: {
     lastMessages: 20,
     workingMemory: {

package/.docs/docs/memory/observational-memory.md

@@ -8,7 +8,7 @@ Observational Memory (OM) is Mastra's memory system for long-context agentic mem
 
 ## Quickstart
 
-Enable `observationalMemory` in the memory options when creating your agent:
+Ensure you have `@mastra/memory` installed in your project. Set `observationalMemory: true` in your Memory config to enable Observational Memory.
 
 ```typescript
 import { Memory } from '@mastra/memory'
@@ -27,7 +27,54 @@ export const agent = new Agent({
 })
 ```
 
-That's it. The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. Config objects also use this model unless you set a different one. To use a different model, pass it in the config object:
+**For AI agents:** Using Observational Memory requires a storage provider! You either need to set it on the Mastra instance at `src/mastra/index.ts` or pass it to the Agent constructor.
+
+The following script creates a local LibSQL database, enables Observational Memory, and uses one resource and thread across two agent calls:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { LibSQLStore } from '@mastra/libsql'
+import { Memory } from '@mastra/memory'
+
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'memory-storage',
+    url: 'file:./memory.db',
+  }),
+  options: {
+    observationalMemory: {
+      model: 'openai/gpt-5-mini',
+    },
+  },
+})
+
+const agent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5-mini',
+  memory,
+})
+
+const memoryOptions = {
+  resource: 'user-123',
+  thread: 'conversation-123',
+}
+
+const firstResponse = await agent.generate('Remember that my favorite color is blue.', {
+  memory: memoryOptions,
+})
+console.log(firstResponse.text)
+
+const secondResponse = await agent.generate('What is my favorite color?', {
+  memory: memoryOptions,
+})
+console.log(secondResponse.text)
+```
+
+The `resource` identifies the user or entity, while the `thread` identifies the conversation. Reuse both values to continue the same conversation. Observational Memory processes the stored history as it grows and replaces older messages with observations when its activation conditions are met.
+
+The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. To use a different model, pass it in the config object:
 
 ```typescript
 const memory = new Memory({
@@ -47,7 +94,7 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 >
 > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
 
-> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, and `@mastra/mongodb` storage adapters. It uses background agents for managing memory. When no model is set, the default model is `google/gemini-2.5-flash`.
+> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, `@mastra/mongodb`, and `@mastra/convex` storage adapters. It uses background agents for managing memory. When no model is set, the default model is `google/gemini-2.5-flash`.
 
 ## Temporal gap markers
 
@@ -237,6 +284,34 @@ new Extractor({
 })
 ```
 
+#### Read extracted values from a stream
+
+Extractor results are emitted when OM completes an observation or reflection. Read both completion data parts from the stream:
+
+```typescript
+const stream = await agent.stream('Remember that I prefer dark mode.')
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'data-om-observation-end' || chunk.type === 'data-om-buffering-end') {
+    const { operationType, extractedValues = {}, extractionFailures = [] } = chunk.data
+
+    for (const [slug, value] of Object.entries(extractedValues)) {
+      console.log(`${operationType} extractor ${slug}:`, value)
+    }
+
+    for (const failure of extractionFailures) {
+      console.error(`Extractor ${failure.slug} failed:`, failure.error)
+    }
+  }
+}
+```
+
+`extractedValues` uses each extractor's slug as its key. Both result fields are optional, and a failed extractor doesn't remove values from successful extractors.
+
+`data-om-observation-end` reports a synchronous completion. `data-om-buffering-end` reports completed background work. Its extractor metadata is persisted immediately, but the buffered content remains inactive until activation. Check `operationType` to determine whether the completed work was an observation or reflection.
+
+See the [`data-om-observation-end`](https://mastra.ai/reference/memory/observational-memory) and [`data-om-buffering-end`](https://mastra.ai/reference/memory/observational-memory) reference tables for the complete payloads.
+
 ### Working memory updates
 
 Use `observationalMemory.observation.manageWorkingMemory` to let the Observer manage working memory automatically. The main agent no longer needs to call the working memory tool while it handles the user request, so working memory updates don't depend on the agent remembering to make them.

package/.docs/docs/memory/overview.md

@@ -81,6 +81,8 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
 
 3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
 
+   **For AI agents:** Important: Add `id` to `LibSQLStore`.
+
    ```typescript
    import { Mastra } from '@mastra/core'
    import { LibSQLStore } from '@mastra/libsql'
@@ -151,6 +153,8 @@ To list all threads for a resource, or retrieve a specific thread, [use the memo
 
 For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.
 
+**For AI agents:** Using Observational Memory requires a storage provider! You either need to set it on the Mastra instance at `src/mastra/index.ts` or pass it to the Agent constructor.
+
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { Memory } from '@mastra/memory'

package/.docs/docs/memory/working-memory.md

@@ -403,7 +403,7 @@ By default, working memory reaches the model as part of the system message. You
 
 ```typescript
 const memory = new Memory({
-  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
   options: {
     workingMemory: {
       enabled: true,

package/.docs/docs/observability/integrations/bridges/otel.md

@@ -126,9 +126,7 @@ export const mastra = new Mastra({
       },
     },
   }),
-  agents: {
-    /* your agents */
-  },
+  agents: {/* your agents */},
 })
 ```
 

package/.docs/docs/observability/integrations/exporters/braintrust.md

@@ -109,10 +109,38 @@ new BraintrustExporter({
 
 ## Attach traces to Braintrust evals
 
+Install the Braintrust SDK directly when your application uses `Eval()`, `logger.traced()`, or `currentSpan`:
+
+**npm**:
+
+```bash
+npm install braintrust@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add braintrust@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add braintrust@latest
+```
+
+**Bun**:
+
+```bash
+bun add braintrust@latest
+```
+
 When you run Mastra inside Braintrust `Eval()` or `logger.traced()`, pass the Braintrust logger and `currentSpan` resolver to the exporter. Import `currentSpan` from the same `braintrust` package instance that creates the eval or traced span.
 
 This helps Mastra attach its spans under the active Braintrust span when your app and `@mastra/braintrust` resolve different installed copies of the Braintrust SDK.
 
+The exporter accepts compatible logger and span objects from Braintrust SDK v2 and v3. Your application's Braintrust SDK version doesn't need to match the version installed by `@mastra/braintrust`.
+
 ```typescript
 import { currentSpan, initLogger } from 'braintrust'
 import { BraintrustExporter } from '@mastra/braintrust'
@@ -144,15 +172,19 @@ await Eval('my-project', {
 })
 ```
 
+If your application upgrades its direct Braintrust dependency from v2 to v3 and uses Nunjucks prompt templates, follow the [Braintrust v2 to v3 migration guide](https://www.braintrust.dev/docs/sdks/typescript/migrations/v2-to-v3).
+
 ## Querying Braintrust with returned `spanId`
 
-For Braintrust, use `spanId` as the root span identifier when searching for traces because Braintrust root-span queries are typically faster than trace-id queries.
+Mastra uses its returned `spanId` as both the Braintrust row ID and span ID. Use it to find the corresponding Braintrust span by `id` or `span_id`.
+
+Braintrust v3 stores a separate W3C trace ID in `root_span_id`, so the returned Mastra `spanId` isn't the Braintrust `root_span_id`.
 
 ```typescript
 const result = await agent.stream('Summarize this ticket')
 
 console.log('Mastra trace ID:', result.traceId)
-console.log('Braintrust root span ID:', result.spanId)
+console.log('Braintrust row and span ID:', result.spanId)
 
 // Use result.spanId in your Braintrust lookup/query path
 ```

package/.docs/docs/observability/integrations/exporters/otel.md

@@ -425,9 +425,7 @@ To disable a signal, set the `signals` option:
 
 ```typescript
 new OtelExporter({
-  provider: {
-    /* ... */
-  },
+  provider: {/* ... */},
   signals: {
     traces: true, // default
     logs: false, // disable log export

package/.docs/docs/server/auth/simple-auth.md

@@ -74,9 +74,7 @@ Add custom headers using the `headers` option:
 
 ```typescript
 new SimpleAuth({
-  tokens: {
-    /* ... */
-  },
+  tokens: {/* ... */},
   headers: ['X-API-Key', 'X-Custom-Auth'],
 })
 ```

package/.docs/docs/server/request-context.md

@@ -247,6 +247,8 @@ auth: {
 }
 ```
 
+When the resource ID is derived this way, clients can omit `memory.resource` from agent generate and stream request bodies — the server-derived value is used instead (and always takes precedence over any client-provided value). If a request uses memory and neither the body nor the request context provides a resource ID, the server responds with a 400 error.
+
 You can also set these keys manually in middleware:
 
 ```typescript

package/.docs/docs/studio/overview.md

@@ -91,6 +91,8 @@ See [request context](https://mastra.ai/docs/server/request-context) for configu
 
 ## Evaluation
 
+Use the date filter to limit score metrics to a preset or custom time range.
+
 ### Scorers
 
 The Scorers tab displays the results of your agent's scorers as they run. When messages pass through your agent, the defined scorers evaluate each output asynchronously and render their results here. This allows you to understand how your scorers respond to different interactions, compare performance across test cases, and identify areas for improvement.

package/.docs/docs/voice/livekit.md

@@ -360,7 +360,7 @@ import { LibSQLStore } from '@mastra/libsql'
 import { Observability, MastraStorageExporter } from '@mastra/observability'
 
 export const mastra = new Mastra({
-  storage: new LibSQLStore({ url: 'file:./voice-agent.db' }),
+  storage: new LibSQLStore({ id: 'voice-agent-storage', url: 'file:./voice-agent.db' }),
   observability: new Observability({
     configs: {
       default: {

package/.docs/docs/workflows/control-flow.md

@@ -591,9 +591,7 @@ const embedStep = createStep({
   inputSchema: z.object({ chunk: z.string() }),
   outputSchema: z.object({ embedding: z.array(z.number()) }),
   execute: async ({ inputData }) => ({
-    embedding: [
-      /* vector embedding */
-    ],
+    embedding: [/* vector embedding */],
   }),
 })
 

package/.docs/docs/workspace/filesystem.md

@@ -23,6 +23,7 @@ Available providers:
 - [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem): Stores files in a directory on disk
 - [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem): Stores files in Amazon S3 or S3-compatible storage (R2, MinIO, Tigris)
 - [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem): Stores files in Google Cloud Storage
+- [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem): Stores files in a Mastra Platform workspace bucket
 - [`GoogleDriveFilesystem`](https://mastra.ai/reference/workspace/google-drive-filesystem): Stores files inside a Google Drive folder
 - [`AzureBlobFilesystem`](https://mastra.ai/reference/workspace/azure-blob-filesystem): Stores files in Azure Blob Storage
 - [`FilesSDKFilesystem`](https://mastra.ai/reference/workspace/files-sdk-filesystem): Stores files in any [FilesSDK](https://files-sdk.dev) adapter (S3, R2, GCS, Azure Blob, Vercel Blob, local filesystem, and more) — useful when you want one provider that can target multiple backends

package/.docs/docs/workspace/sandbox.md

@@ -26,6 +26,7 @@ A sandbox provider executes commands in a controlled environment:
 - [`DaytonaSandbox`](https://mastra.ai/reference/workspace/daytona-sandbox): Executes commands in isolated Daytona cloud sandboxes
 - [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox): Executes commands in isolated E2B cloud sandboxes
 - [`ModalSandbox`](https://mastra.ai/reference/workspace/modal-sandbox): Executes commands in isolated Modal cloud sandboxes
+- [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox): Executes commands in a sandbox tied to a Mastra Platform environment
 - [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox): Executes commands in ephemeral, isolated Railway cloud sandboxes
 
 ## Basic usage

package/.docs/guides/build-your-ui/ai-sdk-ui.md

@@ -1134,6 +1134,7 @@ import { LibSQLStore } from '@mastra/libsql'
 export const mastra = new Mastra({
   workflows: { approvalWorkflow },
   storage: new LibSQLStore({
+    id: 'mastra-storage',
     url: 'file:../mastra.db',
   }),
   server: {

package/.docs/guides/guide/signal-provider.md

@@ -26,6 +26,7 @@ import { LibSQLStore } from '@mastra/libsql'
 
 export const mastra = new Mastra({
   storage: new LibSQLStore({
+    id: 'mastra-storage',
     url: 'file:./mastra.db',
   }),
 })
@@ -133,6 +134,7 @@ import { devAgent } from './agents/dev-agent'
 export const mastra = new Mastra({
   agents: { devAgent },
   storage: new LibSQLStore({
+    id: 'mastra-storage',
     url: 'file:./mastra.db',
   }),
 })

package/.docs/guides/migrations/vnext-to-standard-apis.md

@@ -245,9 +245,7 @@ The following options are available in the standard `.stream()` and `generate()`
   const result = await agent.stream(messages, {
     prepareStep: ({ step, state }) => {
       console.log('About to execute step:', step)
-      return {
-        /* modified state */
-      }
+      return {/* modified state */}
     },
   })
   ```

package/.docs/models/environment-variables.md

@@ -132,6 +132,7 @@ List of required environment variables for each model provider and gateway suppo
 | [Tencent Token Plan](https://mastra.ai/models/providers/tencent-token-plan)                    | `tencent-token-plan/*`     | `TENCENT_TOKEN_PLAN_API_KEY`                                                                          |
 | [Tencent TokenHub](https://mastra.ai/models/providers/tencent-tokenhub)                        | `tencent-tokenhub/*`       | `TENCENT_TOKENHUB_API_KEY`                                                                            |
 | [The Grid AI](https://mastra.ai/models/providers/the-grid-ai)                                  | `the-grid-ai/*`            | `THEGRIDAI_API_KEY`                                                                                   |
+| [Thinking Machines](https://mastra.ai/models/providers/thinkingmachines)                       | `thinkingmachines/*`       | `TINKER_API_KEY`                                                                                      |
 | [Tinfoil](https://mastra.ai/models/providers/tinfoil)                                          | `tinfoil/*`                | `TINFOIL_API_KEY`                                                                                     |
 | [Together AI](https://mastra.ai/models/providers/togetherai)                                   | `togetherai/*`             | `TOGETHER_API_KEY`                                                                                    |
 | [TrustedRouter](https://mastra.ai/models/providers/trustedrouter)                              | `trustedrouter/*`          | `TRUSTEDROUTER_API_KEY`                                                                               |