@mastra/mcp-docs-server 1.3.7-alpha.1 → 1.3.7-alpha.5

package/.docs/docs/agents/guardrails.md

@@ -232,7 +232,7 @@ inputProcessors: [
 
 ## Violation callbacks
 
-All processors support an `onViolation` callback that fires when a policy violation is detected, regardless of strategy. Use it for side effects like alerting, logging to external systems, or sending notifications.
+Processors support an `onViolation` callback that fires when a policy violation aborts the run, for example with the `block` strategy. Aborts from `processToolResult`, and from processor workflows while streaming output, don't call it. Some processors also call it directly: `RegexFilterProcessor` when it redacts content, and `TokenCostControl` when it warns. Strategies that only log, such as `ModerationProcessor`'s `warn`, don't call it. Use it for side effects like alerting, logging to external systems, or sending notifications.
 
 The callback receives a `ProcessorViolation` object with `processorId`, `message`, and `detail` (processor-specific metadata).
 
@@ -263,7 +263,7 @@ moderation.onViolation = ({ processorId, message, detail }) => {
 }
 ```
 
-The `onViolation` property is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any processor, including custom ones, can use it. The runner automatically invokes `onViolation` when any processor calls `abort()`. For processors using a `warn` strategy (like `TokenCostControl`), the callback also fires on warnings without blocking the request.
+The `onViolation` property is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any processor, including custom ones, can use it. The runner automatically invokes `onViolation` when a processor calls `abort()`, except on the paths noted above. For processors using a `warn` strategy (like `TokenCostControl`), the callback also fires on warnings without blocking the request.
 
 Errors thrown by runner-invoked callbacks after `abort()` are silently caught to prevent interfering with the processor's main logic. On the `TokenCostControl` warning path, callback errors are caught and logged through the Mastra logger.
 

package/.docs/docs/auth/fga.md

@@ -79,7 +79,6 @@ resourceMapping: {
 - `user`: the authenticated user
 - `resourceId`: the owning Mastra resource ID when available (for example, a thread's `resourceId`)
 - `requestContext`: the current request context for advanced tenant resolution
-- `metadata`: provider-specific metadata for the attempted action
 
 Return `undefined` from `deriveId()` to fall back to the original Mastra resource ID.
 

package/.docs/docs/deployment/workers.md

@@ -146,7 +146,7 @@ Workers are internal infrastructure. They're not exposed to end users and don't
 In a split deployment:
 
 - **The API server is the only public-facing process**: It serves all client HTTP requests. These requests include REST endpoints and agent interactions, plus workflow triggers and custom routes.
-- **Workers connect outbound only**: They pull events from the distributed PubSub backend and read/write to the shared storage database. They don't accept inbound traffic from clients.
+- **Workers don't serve client traffic**: They pull events from the distributed PubSub backend and read/write to the shared storage database. Each worker process also listens on `PORT` (default `4111`) for internal health checks. `/health` reports readiness and `/config` returns the worker configuration to authorized callers. Keep this port on the private network.
 - **The orchestration worker calls the API internally**: It sends step execution requests to the API over the container network using `MASTRA_STEP_EXECUTION_URL`. This is internal service-to-service communication, not a public endpoint.
 
 All three worker types (orchestration, scheduler, background task) sit behind the API on a private network. They share access to the PubSub backend and storage database but never receive traffic directly from clients. HTTP routes for worker-related features run on the API server rather than the worker process. One example is creating a token for a voice integration.

package/.docs/docs/evals/datasets.md

@@ -219,7 +219,7 @@ MongoDB storage requires a replica set or sharded deployment with transaction su
 
 ## Listing and searching items
 
-[`listItems()`](https://mastra.ai/reference/datasets/listItems) supports pagination and full-text search:
+[`listItems()`](https://mastra.ai/reference/datasets/listItems) supports pagination and case-insensitive substring search:
 
 ```typescript
 // Paginated list
@@ -228,7 +228,7 @@ const { items, pagination } = await dataset.listItems({
   perPage: 50,
 })
 
-// Full-text search
+// Substring search
 const { items: matches } = await dataset.listItems({
   search: 'Hello',
 })
@@ -240,11 +240,10 @@ const { items: v2Matches } = await dataset.listItems({
   page: 0,
   perPage: 50,
 })
-
-// Version-only snapshot returns a bare DatasetItem[]
-const v2Items = await dataset.listItems({ version: 2 })
 ```
 
+Calling `listItems({ version })` without `search`, `page`, or `perPage` returns a bare `DatasetItem[]`. This form is deprecated. Pass `page` and `perPage` to always receive the paginated shape.
+
 ## Versioning
 
 Adding, updating, or deleting dataset items bumps the dataset version. Purging an item's stored content with [`purgeItem()`](https://mastra.ai/reference/datasets/purgeItem) doesn't create a new version. This lets you pin experiments to a specific snapshot of the data while erasing sensitive content without changing the version history.
@@ -278,7 +277,7 @@ for (const row of history) {
 Fetch the exact items that existed at a past version:
 
 ```typescript
-const items = await dataset.listItems({ version: 2 })
+const { items } = await dataset.listItems({ version: 2, page: 0, perPage: 100 })
 ```
 
 You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/evals/experiments). Visit the [`Dataset` reference](https://mastra.ai/reference/datasets/dataset) for the full list of methods and parameters.

package/.docs/docs/evals/gates-and-verdicts.md

@@ -4,7 +4,7 @@
 
 # Gates and verdicts
 
-Gates and verdicts add severity semantics to `runEvals`. Gates are scorers that must score 1.0, hard requirements that block a run. Thresholds are minimum acceptable scores on tracked metrics. The verdict summarizes the outcome as `passed`, `scored`, or `failed`.
+Gates and verdicts add severity semantics to `runEvals`. Gates are scorers that must score 1.0, hard requirements that block a run. Thresholds are lower and/or upper bounds on the average score of tracked metrics. The verdict summarizes the outcome as `passed`, `scored`, or `failed`.
 
 ## When to use gates and verdicts
 
@@ -50,7 +50,7 @@ The verdict field is omitted when no gates or threshold-bearing scorers are prov
 
 ## Gates
 
-Gates are scorers passed via the `gates` field. They run before regular scorers on each data item. A gate must average a score of 1.0 across all data items to pass.
+Gates are scorers passed via the `gates` field. They run before regular scorers on each data item. A gate must average a score of 1.0 across the data items it could score to pass. Items where the gate returns `notScorable()` are excluded from the average, and a gate that throws an error counts as 0 for that item.
 
 ```typescript
 import { runEvals } from '@mastra/core/evals'
@@ -87,7 +87,7 @@ You must provide at least one scorer or gate, a run with neither throws an error
 
 ## Thresholds
 
-Wrap a scorer in `{ scorer, threshold }` to set pass/fail bounds. The threshold is compared against the scorer's average score across all data items.
+Wrap a scorer in `{ scorer, threshold }` to set pass/fail bounds. The threshold is compared against the scorer's average score across scored data items. Results that return `notScorable()` are left out of the average.
 
 A `threshold` can be:
 

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

@@ -63,7 +63,14 @@ A local `.env` file is optional. Environment variables stored on the platform ar
    > })
    > ```
 
-   If the build statically finds `backgroundTasks.enabled: true`, the deploy artifact includes a worker manifest. Mastra Cloud automatically provisions or updates a dedicated worker service from the same artifact. No separate toggle or add-on is required.
+   If the build statically finds `backgroundTasks.enabled: true`, the CLI decides whether to run background tasks on a dedicated worker service or in-process inside the API server container:
+
+   - A dedicated worker service requires Redis for coordination. Without a usable `REDIS_URL` in the deploy env, background tasks run in-process.
+   - With Redis available, the CLI uses a dedicated worker service when the environment already has one, when you pass `--yes`, or when the deploy runs headless. Otherwise it asks whether to provision one.
+   - Pass `--workers dedicated` or `--workers in-process` to skip the decision. `--workers dedicated` fails if `REDIS_URL` is missing.
+   - Dedicated worker services are rolling out gradually, so for organizations without access the CLI omits the worker manifest and background tasks run in-process, even with Redis and `--workers dedicated`.
+
+   When a dedicated worker service is chosen, the deploy artifact includes a worker manifest, and Mastra Cloud provisions or updates the worker service from the same artifact.
 
    Removing `backgroundTasks` or setting `enabled: false` in a later deploy removes the manifest and spins down the existing worker service. Values that can't be determined statically are omitted from the manifest display, but the worker process still reads the complete configuration from your bundled code.
 

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

@@ -207,15 +207,17 @@ If `mastra init` configured observability for the project, use the token it wrot
 
 You can run `--dry-run` without this token because a dry run doesn't contact the collector or query API.
 
-Specify the destination with `--project`, or set `MASTRA_PROJECT_ID`. You can use a project name, slug, or ID with `--project`:
+`--target-project` names the destination: the Mastra Platform project that receives the traces. Specify it with a project name, slug, or ID, or set `MASTRA_PROJECT_ID`:
 
 ```bash
-npx mastra traces import langfuse --project my-project --dry-run
+npx mastra traces import langfuse --target-project my-mastra-project --dry-run
 ```
 
-The `--project` flag takes precedence over `MASTRA_PROJECT_ID`. Without either value, the CLI uses the project linked in `.mastra-project.json`.
+The `--target-project` flag takes precedence over `MASTRA_PROJECT_ID`. Without either value, the CLI uses the project linked in `.mastra-project.json`.
 
-For a headless environment, set the API token and organization ID. The command uses `MASTRA_API_TOKEN` for project discovery, upload, and read-back. Set the project ID or pass `--project`:
+The source project isn't a command-line option. The provider credentials in `.env` select it, and the preparation summary names it before anything is uploaded.
+
+For a headless environment, set the API token and organization ID. The command uses `MASTRA_API_TOKEN` for project discovery, upload, and read-back. Set the project ID or pass `--target-project`:
 
 ```bash
 MASTRA_API_TOKEN=<mastra-api-token>
@@ -225,7 +227,7 @@ MASTRA_PROJECT_ID=<project-id>
 
 ### Configure Langfuse
 
-Create [project API keys in Langfuse](https://langfuse.com/docs/api-and-data-platform/features/public-api), then add them to `.env` or `.env.local` in the directory where you run the command:
+Langfuse API keys belong to one Langfuse project, so they also select the source project. Create [project API keys in Langfuse](https://langfuse.com/docs/api-and-data-platform/features/public-api), then add them to `.env` or `.env.local` in the directory where you run the command:
 
 ```bash
 LANGFUSE_PUBLIC_KEY=<langfuse-public-key>
@@ -243,12 +245,12 @@ LANGFUSE_BASE_URL=https://us.cloud.langfuse.com
 Run a dry run before uploading:
 
 ```bash
-npx mastra traces import langfuse --project my-project --dry-run
+npx mastra traces import langfuse --target-project my-mastra-project --dry-run
 ```
 
 The dry run reads the source, prepares valid Mastra traces locally, and reports:
 
-- The source and destination projects.
+- The source Langfuse project by name and ID, and the destination Mastra Platform project.
 - The fixed import window.
 - Prepared and skipped trace and span counts.
 - The size of the prepared local data.
@@ -258,22 +260,24 @@ It doesn't upload traces. The command prints a `--resume` command that uploads t
 
 ### Choose the import window
 
-By default, the command selects the last 30 days, ending when the import starts. Use `--from` and `--to` to choose a smaller window:
+By default, the command selects the last 30 days, ending when the import starts. Use `--since` and `--until` to choose a smaller window:
 
 ```bash
 npx mastra traces import langfuse \
-  --project my-project \
-  --from "$FROM" \
-  --to "$TO" \
+  --target-project my-mastra-project \
+  --since "$SINCE" \
+  --until "$UNTIL" \
   --dry-run
 ```
 
-Set `FROM` and `TO` to ISO 8601 dates or timestamps. The following rules apply:
+Set `SINCE` and `UNTIL` to ISO 8601 dates or timestamps. The following rules apply:
 
-- `--to` can't be in the future or outside the current 30-day Platform retention period.
-- `--from` must be earlier than `--to` and inside the current retention period.
+- `--until` can't be in the future or outside the current 30-day Platform retention period.
+- `--since` must be earlier than `--until` and inside the current retention period.
 - The selected window can't exceed 30 days.
-- If only `--to` is set, the default start is the later of 30 days before `--to` and the current retention boundary.
+- If only `--until` is set, the default start is the later of 30 days before `--until` and the current retention boundary.
+
+Commands written with the earlier `--from` and `--to` names still work.
 
 Trace eligibility is based on the root observation's start time. The Langfuse adapter discovers roots in the selected window and then reads all currently available observations for each selected trace. It skips the complete trace if the available parent-child tree or timestamps are invalid.
 
@@ -282,13 +286,13 @@ Trace eligibility is based on the root observation's start time. The Langfuse ad
 Run the command without `--dry-run` to upload the prepared traces:
 
 ```bash
-npx mastra traces import langfuse --project my-project
+npx mastra traces import langfuse --target-project my-mastra-project
 ```
 
 The CLI displays the preparation summary and asks for confirmation before upload. Pass `--yes` to skip this prompt in an automated environment:
 
 ```bash
-npx mastra traces import langfuse --project my-project --yes
+npx mastra traces import langfuse --target-project my-mastra-project --yes
 ```
 
 The importer keeps every trace in one upload request and checkpoints progress only after Mastra Platform acknowledges the batch. Temporary source and destination failures use bounded retries.
@@ -304,10 +308,10 @@ Use the exact command printed by the CLI when a dry run, cancellation, interrupt
 ```bash
 npx mastra traces import langfuse \
   --resume 00000000-0000-0000-0000-000000000000 \
-  --project my-project
+  --target-project my-mastra-project
 ```
 
-A resumed import must use the original provider and destination project. Its saved date window can't be changed, so `--from`, `--to`, and `--dry-run` can't be combined with `--resume`.
+A resumed import must use the original provider and destination project. Its saved date window can't be changed, so `--since`, `--until`, and `--dry-run` can't be combined with `--resume`.
 
 Resume behavior depends on where the command stopped:
 
@@ -337,7 +341,9 @@ These files can contain trace content. Mastra creates the import directory and f
 For Langfuse imports:
 
 - Observations become Mastra spans with their parent-child relationships and timestamps.
+- Langfuse `AGENT`, `TOOL`, and `EVALUATOR` observations, and plain spans that carry OpenTelemetry GenAI attributes such as `gen_ai.operation.name: invoke_agent`, keep their primitive type and name. Mastra Platform shows them in the Primitive type and Primitive name columns and includes them in those filters, like native traces.
 - Supported fields such as names, input, output, errors, model details, usage, cost, tags, and source context are mapped when present.
+- Environments you set in Langfuse, such as `staging`, are kept. Langfuse's built-in `default` environment isn't copied. Those traces have no environment in Mastra, and Mastra Studio shows them for every environment.
 - Destination trace and span IDs are deterministic. Original Langfuse IDs remain in span metadata for correlation.
 - Unknown Langfuse observation types become generic spans and produce a warning instead of being silently discarded.
 - Only trace observations are imported. Scores, feedback, datasets, attachments, and logs aren't imported.

package/.docs/docs/mastra-platform/system-environment-variables.md

@@ -37,7 +37,7 @@ Attaching a hosted database adds its connection variables to the environments th
 | -------- | ---------------------------------------- |
 | Turso    | `TURSO_DATABASE_URL`, `TURSO_AUTH_TOKEN` |
 | Neon     | `DATABASE_URL`                           |
-| Postgres | `POSTGRES_URL`                           |
+| Postgres | `DATABASE_URL`                           |
 
 Values are resolved at deploy time and never stored in your project. An environment-scoped database replaces the values of a project-scoped database of the same provider for that environment.
 

package/.docs/docs/mastra-platform/trace-intelligence.md

@@ -83,7 +83,7 @@ Entities appear while their signals are still collecting or processing. The inde
 
 ### Configure a custom signal
 
-Users with project management permission can configure custom signals without leaving Intelligence:
+Organization admins can configure custom signals without leaving Intelligence:
 
 1. Return to the entity index and select **Signal settings**.
 2. Select **Create signal**, provide a stable signal name, display label, description, and signal instructions, then save it. Definitions and their versions are shared across the organization.

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

@@ -82,8 +82,8 @@ export const mastra = new Mastra({
 
 - `start()` provisions a fresh sandbox (or reattaches when you passed `sandboxId`).
 - `executeCommand()` runs commands against it.
-- `stop()` tears down the remote sandbox while preserving its recovery checkpoint when it has one.
-- `destroy()` also releases the recovery checkpoint associated with a caller-supplied recovery `id`.
+- `stop()` releases this process's lease without touching the remote sandbox. The VM keeps running under the environment's idle policy, and a later `start()` with the same `id` or `sandboxId` reattaches to it.
+- `destroy()` releases the VM. On Railway, it also deletes the recovery checkpoint associated with a caller-supplied recovery `id`. On E2B, it only kills the VM, and any snapshot you captured remains yours to manage.
 
 A statically configured `PlatformSandbox` is shared across every request and agent using that configuration rather than creating separate sandboxes for requests or memory threads. `PlatformFilesystem` is also a separate provider: configuring both providers doesn't mount the environment bucket inside the sandbox.
 

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

@@ -158,7 +158,7 @@ const memory = new Memory({
 })
 ```
 
-OM requires a storage adapter that supports it: `@mastra/libsql`, `@mastra/pg`, `@mastra/mongodb`, or `@mastra/oracledb`.
+OM requires a storage adapter that supports it: `@mastra/libsql`, `@mastra/pg`, `@mastra/mongodb`, `@mastra/mysql`, `@mastra/convex`, or `@mastra/oracledb`.
 
 > **Note:** If you switch the Observer to a less capable model and see facts attributed to a generic `User` instead of individual participants, use [`observation.instruction`](https://mastra.ai/reference/memory/observational-memory) to explain how to interpret the `<turn>` tag.
 

package/.docs/docs/observability/metrics/overview.md

@@ -10,7 +10,7 @@ Mastra emits:
 
 - **Duration metrics** for agent runs, workflows, tools, model calls, and processors
 - **Token usage metrics** for model input and output, including detailed token categories when the provider reports them
-- **Cost estimates** calculated from token usage, provider, model, and an embedded pricing registry
+- **Cost estimates** calculated from token usage, provider, model, and model prices from [models.dev](https://models.dev)
 
 Metrics retain trace correlation context, so you can investigate a change in a chart by finding the related span. See the [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics) for metric names, labels, and cost fields.
 

package/.docs/docs/observability/tracing/overview.md

@@ -919,6 +919,12 @@ app.post('/api/analyze', async (req, res) => {
 
 This creates a single distributed trace that includes both the HTTP request handling and the Mastra agent execution, viewable in your observability platform of choice.
 
+### MCP calls
+
+Model Context Protocol (MCP) calls link the caller's trace and the server's trace without any setup. When an agent or workflow calls a tool through `MCPClient`, the `MCPServer` that handles it keeps its own trace and records a link to the tool call span, and the tool call span links back to the server's span. Each side keeps its own trace, root span, and trace summary. When the server uses a tracing bridge and its HTTP instrumentation continues the caller's trace, the request joins that trace instead. Mastra storage saves the links with the spans, and exporters with span link support send them too.
+
+This also works with non-Mastra software on either side. See the [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server) for details, and the [`MCPClient` reference](https://mastra.ai/reference/tools/mcp-client) to send your own trace context.
+
 ## What gets traced
 
 Mastra automatically creates spans for:

package/.docs/docs/sandbox/computer.md

@@ -10,19 +10,19 @@ Sandboxes that run a desktop environment can expose screenshot, mouse, and keybo
 
 ## Computer tools
 
-| Tool                       | Does                                                                             |
-| -------------------------- | -------------------------------------------------------------------------------- |
-| `computer_screenshot`      | Captures the desktop as a PNG image and returns it to the model as native media. |
-| `computer_click`           | Presses and releases the left mouse button at pixel coordinates.                 |
-| `computer_double_click`    | Presses the left mouse button twice at pixel coordinates.                        |
-| `computer_right_click`     | Presses and releases the right mouse button at pixel coordinates.                |
-| `computer_move_mouse`      | Moves the cursor to pixel coordinates without pressing a button.                 |
-| `computer_drag`            | Presses, drags, and releases between two points.                                 |
-| `computer_type`            | Types text into the focused element.                                             |
-| `computer_press_key`       | Presses a key or key combination, such as `Enter` or `ctrl+s`.                   |
-| `computer_scroll`          | Scrolls up or down.                                                              |
-| `computer_get_screen_info` | Gets the screen dimensions and cursor position.                                  |
-| `computer_wait`            | Waits for the interface to settle.                                               |
+| Tool                                        | Does                                                                             |
+| ------------------------------------------- | -------------------------------------------------------------------------------- |
+| `mastra_workspace_computer_screenshot`      | Captures the desktop as a PNG image and returns it to the model as native media. |
+| `mastra_workspace_computer_click`           | Presses and releases the left mouse button at pixel coordinates.                 |
+| `mastra_workspace_computer_double_click`    | Presses the left mouse button twice at pixel coordinates.                        |
+| `mastra_workspace_computer_right_click`     | Presses and releases the right mouse button at pixel coordinates.                |
+| `mastra_workspace_computer_move_mouse`      | Moves the cursor to pixel coordinates without pressing a button.                 |
+| `mastra_workspace_computer_drag`            | Presses, drags, and releases between two points.                                 |
+| `mastra_workspace_computer_type`            | Types text into the focused element.                                             |
+| `mastra_workspace_computer_press_key`       | Presses a key or key combination, such as `Enter` or `ctrl+s`.                   |
+| `mastra_workspace_computer_scroll`          | Scrolls up or down.                                                              |
+| `mastra_workspace_computer_get_screen_info` | Gets the screen dimensions and cursor position.                                  |
+| `mastra_workspace_computer_wait`            | Waits for the interface to settle.                                               |
 
 ## Configure computer tools
 

package/.docs/docs/sandbox/overview.md

@@ -49,11 +49,11 @@ A static sandbox is shared across every request and memory thread that uses the
 
 Agents receive tools for the capabilities supported by the sandbox backend:
 
-| Tool                 | Does                                                                                                                                                                                                                                    |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `execute_command`    | Runs a shell command and returns stdout, stderr, and the exit code. Supports `background: true` when the backend can spawn long-running processes.                                                                                      |
-| `get_process_output` | Gets stdout, stderr, and status for a background process. Supports `tail` to limit output and `wait: true` to wait for the process to exit. This tool and `kill_process` are only added when the backend supports background processes. |
-| `kill_process`       | Stops a background process and returns its recent output.                                                                                                                                                                               |
+| Tool                 | Does                                                                                                                                                                                                                                                                                                                                                                                                     |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `execute_command`    | Runs a shell command and returns stdout, stderr, and the exit code. Supports `background: true` when the backend can spawn long-running processes.                                                                                                                                                                                                                                                       |
+| `get_process_output` | Gets stdout, stderr, and status for a background process. Supports `tail` to limit output and `wait: true` to wait for the process to exit. For a static sandbox, this tool and `kill_process` are only added when the backend supports background processes. Workspaces that resolve their sandbox per request always include both tools, because capabilities aren't known until the sandbox resolves. |
+| `kill_process`       | Stops a background process and returns its recent output.                                                                                                                                                                                                                                                                                                                                                |
 
 Configured capabilities determine which tools are available. Tool configuration can then disable, rename, or add policies to those tools:
 

package/.docs/docs/server/custom-adapters.md

@@ -162,7 +162,7 @@ async getParams(
   request: MyRequest
 ): Promise<{
   urlParams: Record<string, string>;
-  queryParams: Record<string, string>;
+  queryParams: Record<string, string | string[]>; // repeated keys (?tag=a&tag=b) become arrays
   body: unknown;
 }> {
   return {

package/.docs/docs/server/server-adapters.md

@@ -823,7 +823,7 @@ When using adapters, configure these features directly with your framework. For
 
 Server adapters register MCP (Model Context Protocol) routes during `registerRoutes()` when MCP servers are configured in your Mastra instance. MCP allows external tools and services to connect to your Mastra server and interact with your agents.
 
-Each server is exposed at `/api/mcp/:serverId/mcp` over Streamable HTTP. Because every request is self-contained, the routes work unchanged in serverless environments like Cloudflare Workers or Vercel Edge.
+Each server is exposed at `/api/mcp/:serverId/mcp` over Streamable HTTP. By default the transport keeps session state between requests. For serverless environments like Cloudflare Workers or Vercel Edge, set `mcpOptions: { serverless: true }` to run in stateless mode without session management.
 
 Pass `mcpOptions` to control how the authenticated principal reaches tools. When using the Mastra deployer (the standard `mastra dev` / `mastra build` path), set it in your server config:
 

package/.docs/docs/studio/auth.md

@@ -124,7 +124,7 @@ Permissions follow the pattern `{resource}:{action}`, with optional resource-lev
 | `agents:execute`    | Execute agents only         |
 | `agents:read:my-id` | Read a specific agent by ID |
 
-Resources include `agents`, `workflows`, `tools`, `datasets`, `memory`, `scores`, `observability`, and others. Actions are `read`, `write`, `execute`, and `delete`.
+Resources include `agents`, `workflows`, `tools`, `datasets`, `memory`, `scores`, `observability`, and others. Actions are `read`, `write`, `create`, `delete`, `execute`, `publish`, and `share`.
 
 ### Map external provider roles
 

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

@@ -519,6 +519,34 @@ export const testWorkflow = createWorkflow({})
   .commit();
 ```
 
+### Passing data between iterations
+
+Each iteration of `.dountil()` or `.dowhile()` receives the previous iteration's output as its `inputData`. When input validation is enabled (the default), that output is validated against the loop body's `inputSchema` before the body runs. With an object schema such as `z.object()`, keys the schema doesn't declare are removed. Schemas that allow unknown keys, such as `.passthrough()`, keep them.
+
+When the loop body is a nested workflow, the output is validated against the nested workflow's `inputSchema` and then against its first step's `inputSchema`. A value is only available on the next iteration if the nested workflow returns it and both schemas declare it. This includes values produced inside the nested workflow, such as feedback from a step that suspended and resumed.
+
+To carry data across iterations, declare it in the body's `inputSchema` and return it from the body's last step:
+
+```typescript
+const loopSchema = z.object({
+  draft: z.string(),
+  feedback: z.string().optional(),
+  attempts: z.number(),
+})
+
+const reviewStep = createStep({
+  id: 'review',
+  inputSchema: loopSchema,
+  outputSchema: loopSchema,
+  execute: async ({ inputData }) => {
+    // ...
+    return { draft, feedback, attempts: inputData.attempts + 1 }
+  },
+})
+```
+
+For values that don't belong in the step's input, such as counters or audit data, use [workflow state](https://mastra.ai/docs/workflows/workflow-state) instead.
+
 ### Looping with `.foreach()`
 
 Use `.foreach()` to run the same step for each item in an array. The input must be of type `array` so the loop can iterate over its values, applying the step's logic to each one. See [Choosing the right pattern](#choosing-the-right-pattern) for guidance on when to use `.foreach()` vs other methods.

package/.docs/docs/workflows/time-travel.md

@@ -197,7 +197,7 @@ const result = await run.timeTravel({
 
 ## Error handling
 
-Time travel throws errors in specific situations:
+Time travel throws errors in specific situations. It rejects a call that observes a running snapshot, but it doesn't atomically claim the run. Concurrent calls can both pass the status check and proceed, so guard against duplicates in your application. See [Concurrent time travel calls](https://mastra.ai/reference/workflows/run-methods/timeTravel).
 
 ### Running workflow
 

package/.docs/integrations/databases/clickhouse.md

@@ -232,6 +232,19 @@ The same `client` form is accepted by `ObservabilityStorageClickhouse` and `Obse
 
 `ClickhouseStore` also accepts every option from `ClickHouseClientConfigOptions` (such as `database`, `request_timeout`, `compression`, `keep_alive`, and `max_open_connections`).
 
+`ClickhouseStore` and `ObservabilityStorageClickhouseVNext` apply `clickhouse_settings` to every query they run. On ClickHouse services that keep data in object storage, such as ClickHouse Cloud, limiting read-ahead lowers the memory each observability query uses, but queries that miss the local cache can run slower:
+
+```typescript
+const observabilityStore = new ObservabilityStorageClickhouseVNext({
+  url: process.env.CLICKHOUSE_URL!,
+  username: process.env.CLICKHOUSE_USERNAME!,
+  password: process.env.CLICKHOUSE_PASSWORD!,
+  clickhouse_settings: {
+    filesystem_prefetches_limit: 8,
+  },
+})
+```
+
 ### Replicated clusters
 
 Use `replication` when Mastra writes to a multi-replica ClickHouse cluster through a load balancer.

package/.docs/integrations/observability/langfuse.md

@@ -199,6 +199,14 @@ If you set a custom `traceName` via `mastra.metadata.traceName`, your value take
 
 A run started with `tracingOptions.nestUnderParent` doesn't own the trace, so the exporter doesn't write the trace name, input, output, metadata, user, or session from it. See [Nesting a run under an earlier Mastra run](https://mastra.ai/docs/observability/tracing/overview).
 
+## Filtering observations by span attributes
+
+Observation-level evaluators in Langfuse filter on top-level observation metadata. The exporter promotes each scalar span attribute (string, number, or boolean) that the OpenTelemetry exporter writes as `mastra.<span_type>.<key>` to `langfuse.observation.metadata.<key>`, with the key converted to camelCase. The exporter also sets `agentId`, `agentName`, `spanType`, and `operationName` on each observation.
+
+For a `MODEL_STEP` span this produces `stepIndex` and `isContinued`. To judge each agent run once, against the step that produced the final answer, filter an observation-level evaluator on `spanType` equals `model_step` and `isContinued` equals `"false"`.
+
+Values are sent as strings, so compare against string values such as `"false"` or `"1"`. Span input and output keep their own mapping, and attributes that hold objects or arrays stay in the nested `attributes` metadata only.
+
 ## Custom trace metadata
 
 Langfuse filters and groups traces by top-level metadata only. Nested metadata keys can't be used for filtering or grouping.

package/.docs/integrations/observability/opentelemetry.md

@@ -838,6 +838,8 @@ Both services must have:
 2. W3C Trace Context propagator enabled
 3. Mastra with `OtelBridge` configured
 
+A Mastra `MCPServer` request over HTTP follows the same rule. With this setup, it joins the caller's trace. Without HTTP instrumentation on the server, each request keeps its own trace. In both cases, when a request carries a W3C `traceparent`, in `_meta` or as an HTTP header, the request span links to the caller's span, and the exporter and the bridge send that link as an OpenTelemetry span link. See [Linking to the caller's trace](https://mastra.ai/reference/tools/mcp-server).
+
 ### Using tags
 
 Tags help you categorize and filter traces in your OTEL backend. Add tags when executing agents or workflows:

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

@@ -140,8 +140,8 @@ List of required environment variables for each model provider and gateway suppo
 | [Ofox](https://mastra.ai/models/providers/ofox)                                              | `ofox/*`                   | `OFOX_API_KEY`                                                                                        |
 | [Ollama Cloud](https://mastra.ai/models/providers/ollama-cloud)                              | `ollama-cloud/*`           | `OLLAMA_API_KEY`                                                                                      |
 | [OpenAI](https://mastra.ai/models/providers/openai)                                          | `openai/*`                 | `OPENAI_API_KEY`                                                                                      |
+| [OpenCode](https://mastra.ai/models/providers/opencode)                                      | `opencode/*`               | `OPENCODE_API_KEY`                                                                                    |
 | [OpenCode Go](https://mastra.ai/models/providers/opencode-go)                                | `opencode-go/*`            | `OPENCODE_API_KEY`                                                                                    |
-| [OpenCode Zen](https://mastra.ai/models/providers/opencode)                                  | `opencode/*`               | `OPENCODE_API_KEY`                                                                                    |
 | [OpenReason](https://mastra.ai/models/providers/openreason)                                  | `openreason/*`             | `OPENREASON_API_KEY`                                                                                  |
 | [Opper](https://mastra.ai/models/providers/opper)                                            | `opper/*`                  | `OPPER_API_KEY`                                                                                       |
 | [OrcaRouter](https://mastra.ai/models/providers/orcarouter)                                  | `orcarouter/*`             | `ORCAROUTER_API_KEY`                                                                                  |
@@ -153,6 +153,7 @@ List of required environment variables for each model provider and gateway suppo
 | [Pioneer](https://mastra.ai/models/providers/pioneer)                                        | `pioneer/*`                | `PIONEER_API_KEY`                                                                                     |
 | [Poe](https://mastra.ai/models/providers/poe)                                                | `poe/*`                    | `POE_API_KEY`                                                                                         |
 | [Poolside](https://mastra.ai/models/providers/poolside)                                      | `poolside/*`               | `POOLSIDE_API_KEY`                                                                                    |
+| [Prime Inference](https://mastra.ai/models/providers/prime)                                  | `prime/*`                  | `PRIME_API_KEY`                                                                                       |
 | [Privatemode AI](https://mastra.ai/models/providers/privatemode-ai)                          | `privatemode-ai/*`         | `PRIVATEMODE_API_KEY`                                                                                 |
 | [QiHang](https://mastra.ai/models/providers/qihang-ai)                                       | `qihang-ai/*`              | `QIHANG_API_KEY`                                                                                      |
 | [Qiniu](https://mastra.ai/models/providers/qiniu-ai)                                         | `qiniu-ai/*`               | `QINIU_API_KEY`                                                                                       |

package/.docs/models/gateways/merge-gateway.md

@@ -4,7 +4,7 @@
 
 # ![Merge Gateway logo](https://models.dev/logos/merge-gateway.svg)Merge Gateway
 
-Merge Gateway aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 198 models through Mastra's model router.
+Merge Gateway aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 199 models through Mastra's model router.
 
 Learn more in the [Merge Gateway documentation](https://docs.merge.dev/merge-gateway).
 
@@ -97,6 +97,7 @@ ANTHROPIC_API_KEY=ant-...
 | `google/gemini-3.7-flash`                        |
 | `google/gemini-3.8-flash`                        |
 | `google/gemini-embedding-001`                    |
+| `google/gemini-embedding-2`                      |
 | `google/gemini-flash-latest`                     |
 | `google/gemini-flash-lite-latest`                |
 | `google/gemma-3-12b-it`                          |

package/.docs/models/gateways/netlify.md

@@ -4,7 +4,7 @@
 
 # Netlify
 
-Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 270 models through Mastra's model router.
+Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 274 models through Mastra's model router.
 
 Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
 
@@ -75,6 +75,10 @@ ANTHROPIC_API_KEY=ant-...
 | `gemini/gemini-flash-latest`                                          |
 | `gemini/gemini-flash-lite-latest`                                     |
 | `gemini/gemini-nano-banana-2.1`                                       |
+| `meta/muse-spark-1.1`                                                 |
+| `meta/muse-spark-1.2`                                                 |
+| `meta/muse-spark-1.3`                                                 |
+| `meta/muse-wonder-1.0`                                                |
 | `openai/chat-latest`                                                  |
 | `openai/gpt-4.1`                                                      |
 | `openai/gpt-4.1-mini`                                                 |

package/.docs/models/gateways/openrouter.md

@@ -4,7 +4,7 @@
 
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 379 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 380 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -176,6 +176,7 @@ ANTHROPIC_API_KEY=ant-...
 | `meta/muse-spark-1.2-contributor`                          |
 | `meta/muse-spark-1.3`                                      |
 | `meta/muse-spark-1.3-contributor`                          |
+| `meta/muse-wonder`                                         |
 | `microsoft/phi-4`                                          |
 | `microsoft/wizardlm-2-8x22b`                               |
 | `minimax/minimax-01`                                       |