@mastra/mcp-docs-server 1.3.6 → 1.3.7-alpha.3

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -66,10 +66,20 @@ The detailed breakdown metrics (everything except `total_input` and `total_outpu
 
 ### When cost context is attached
 
-Cost context is attached to token metrics when the provider reports a valid cost for every completed model step or when the embedded pricing registry has a matching entry for the provider and model. Mastra sums the per-step provider costs into one query total. If any completed step lacks a valid reported cost, Mastra uses the pricing registry instead of reporting a partial total. If neither source is available, token metrics are still emitted without cost fields.
+Cost context is attached to token metrics when the provider reports a valid cost for every completed model step or when the pricing registry has a matching entry for the provider and model. Mastra sums the per-step provider costs into one query total. If any completed step lacks a valid reported cost, Mastra uses the pricing registry instead of reporting a partial total. If neither source is available, token metrics are still emitted without cost fields.
 
 A caller-supplied `costContext` takes precedence over provider-reported costs and pricing registry estimates. Provider-reported totals use `costMetadata.source: 'provider_reported'`, `costMetadata.scope: 'query_total'`, and `costMetadata.reportedStepCount` to identify the source, scope, and number of completed steps included in the total.
 
+### Where prices come from
+
+The pricing registry uses model prices from [models.dev](https://models.dev). `@mastra/observability` includes a snapshot of these prices, and each new release of the package includes recent prices. Stored cost estimates aren't recalculated when prices change.
+
+When you run `mastra dev`, Mastra also refreshes prices from models.dev in the background once a day, and when a model has no price. Cost estimates don't wait for a refresh, so the first call to a newly released model can still have no cost. In other environments, such as production, you can turn on the refresh with `MASTRA_AUTO_REFRESH_PRICING=true`.
+
+Refreshed prices are cached in `~/.cache/mastra/pricing-data.json` and reused by later processes. If a refresh fails, Mastra keeps the prices it already has.
+
+To use only the bundled snapshot, set `MASTRA_AUTO_REFRESH_PRICING=false`. Setting `MASTRA_OFFLINE=true` also turns off the refresh.
+
 ### What cost fields may be included
 
 | Field           | Description                                                                                                        |

package/.docs/reference/observability/tracing/interfaces.md

@@ -216,6 +216,9 @@ interface Span<TType extends SpanType> {
   /** Tags for categorizing traces (only present on root spans) */
   tags?: string[]
 
+  /** Spans in other traces this span is related to */
+  links?: SpanLink[]
+
   /** End the span */
   end(options?: EndSpanOptions<TType>): void
 
@@ -778,6 +781,12 @@ interface MCPServerRequestAttributes {
 
   /** Client implementation version, when the client reported one */
   clientVersion?: string
+
+  /** W3C `traceparent` the caller sent, when it parses */
+  callerTraceparent?: string
+
+  /** W3C `tracestate` the caller sent with a valid `traceparent`, capped at 512 characters */
+  callerTracestate?: string
 }
 ```
 
@@ -998,6 +1007,23 @@ interface StartSpanOptions<TType extends SpanType> {
 
   /** Options passed when using a custom sampler strategy */
   customSamplerOptions?: CustomSamplerOptions
+
+  /** Spans in other traces this span is related to. Links with invalid IDs are ignored. */
+  links?: SpanLink[]
+}
+```
+
+### `SpanLink`
+
+A reference to a span in another trace, such as the caller's span when an `MCPServer` serves a request. Unlike a parent, a link doesn't put the two spans in the same trace.
+
+```typescript
+interface SpanLink {
+  /** Trace ID of the linked span (1-32 hexadecimal characters) */
+  traceId: string
+
+  /** Span ID of the linked span (1-16 hexadecimal characters) */
+  spanId: string
 }
 ```
 

package/.docs/reference/observability/tracing/spans.md

@@ -207,6 +207,8 @@ When tracing is disabled (sampling returns false), NO-OP spans are returned:
 class NoOpSpan<TType extends SpanType> extends BaseSpan<TType>
 ```
 
+`NoOpSpan` is exported from `@mastra/observability`. It extends that package's abstract `BaseSpan` class, which implements the `Span` interface. That class is different from the `BaseSpan` interface described on this page.
+
 A span that performs no operations. All methods are no-ops:
 
 - `id` returns `'no-op'`

package/.docs/reference/processors/moderation-processor.md

@@ -48,7 +48,7 @@ const processor = new ModerationProcessor({
 
 **id** (`string`): Processor identifier set to 'moderation'
 
-**name** (`string`): Optional processor display name
+**name** (`string`): Processor display name, always 'Moderation'
 
 **processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to moderate content before sending to LLM
 

package/.docs/reference/processors/prompt-injection-detector.md

@@ -48,9 +48,9 @@ const processor = new PromptInjectionDetector({
 
 **id** (`string`): Processor identifier set to 'prompt-injection-detector'
 
-**name** (`string`): Optional processor display name
+**name** (`string`): Processor display name, always 'Prompt Injection Detector'
 
-**processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to detect prompt injection attempts before sending to LLM
+**processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; requestContext?: RequestContext; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to detect prompt injection attempts before sending to LLM
 
 ## Extended usage example
 

package/.docs/reference/processors/provider-history-compat.md

@@ -54,14 +54,18 @@ Registering in `errorProcessors` alone, as the example above does, covers both h
 
 `ProviderHistoryCompat` includes these built-in compatibility rules:
 
-| Rule                                        | Provider                         | Timing                      | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| ------------------------------------------- | -------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `anthropic-tool-id-format`                  | Anthropic                        | Preemptive prompt rewrite   | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` in the outbound prompt, on both the call and its result. A sanitized ID that would collide with one already in the prompt gets a `_2`, `_3`, … suffix. The provider's rejection never fires, and persisted history keeps the original IDs. A reactive fallback covers providers the preemptive check doesn't recognize, such as Vertex-hosted Claude.     |
-| `cerebras-strip-reasoning-content`          | Cerebras                         | Preemptive prompt rewrite   | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields.                                                                                                                                                                                                                                                                                                |
-| `anthropic-strip-foreign-reasoning-content` | Anthropic                        | Preemptive prompt rewrite   | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved.                                                                                                                                                                                                                                                                                                      |
-| `anthropic-strip-foreign-signed-reasoning`  | Anthropic-compatible             | Preemptive prompt rewrite   | Drops signed thinking from the outbound prompt when its origin turn was stamped with a different provider (for example Kimi For Coding ↔ `anthropic/claude-sonnet-4-6`), since the receiving provider can't verify another provider's signature. Turns emptied of all content by the drop are removed from the prompt. Unstamped history is left untouched.                                                                      |
-| `azure-system-reminder-transform`           | Azure OpenAI                     | Preemptive prompt rewrite   | Renames `<system-reminder>` wrappers in user text and system instructions to `<memory-context>` for the outbound request. Stored history remains unchanged.                                                                                                                                                                                                                                                                      |
-| `openai-orphan-item-id`                     | OpenAI, Azure OpenAI (Responses) | Reactive API error recovery | Recovers history that OpenAI rejects with `Item 'msg_…' of type 'message' was provided without its required 'reasoning' item`. Drops the Responses `itemId` from every item-bearing part of an assistant message that carries one but has no `reasoning` part, and retries. The message then replays by value instead of as an unsatisfiable `item_reference`. The repair is applied to the in-memory list for the current turn. |
+| Rule                                             | Provider                                       | Timing                      | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------------ | ---------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `strip-foreign-provider-executed-tools`          | Anthropic, OpenAI, Azure OpenAI, Google/Vertex | Preemptive prompt rewrite   | Removes provider-executed tool calls and their paired results from the outbound prompt when they came from a different provider family, since the receiving provider can't resolve another provider's tool IDs. Persisted history is left untouched.                                                                                                                                                                             |
+| `anthropic-tool-id-format`                       | Anthropic                                      | Preemptive prompt rewrite   | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` in the outbound prompt, on both the call and its result. A sanitized ID that would collide with one already in the prompt gets a `_2`, `_3`, … suffix. The provider's rejection never fires, and persisted history keeps the original IDs. A reactive fallback covers providers the preemptive check doesn't recognize, such as Vertex-hosted Claude.     |
+| `cerebras-strip-reasoning-content`               | Cerebras                                       | Preemptive prompt rewrite   | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields.                                                                                                                                                                                                                                                                                                |
+| `anthropic-strip-empty-signed-reasoning-content` | Anthropic                                      | Preemptive prompt rewrite   | Removes assistant `reasoning` parts that carry an Anthropic signature but have empty text, which legacy records can contain. Anthropic signs the exact thinking text, so the mismatched pair would be rejected.                                                                                                                                                                                                                  |
+| `anthropic-strip-foreign-reasoning-content`      | Anthropic                                      | Preemptive prompt rewrite   | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved.                                                                                                                                                                                                                                                                                                      |
+| `anthropic-strip-foreign-signed-reasoning`       | Anthropic-compatible                           | Preemptive prompt rewrite   | Drops signed thinking from the outbound prompt when its origin turn was stamped with a different provider (for example Kimi For Coding ↔ `anthropic/claude-sonnet-4-6`), since the receiving provider can't verify another provider's signature. Turns emptied of all content by the drop are removed from the prompt. Unstamped history is left untouched.                                                                      |
+| `azure-system-reminder-transform`                | Azure OpenAI                                   | Preemptive prompt rewrite   | Renames `<system-reminder>` wrappers in user text and system instructions to `<memory-context>` for the outbound request. Stored history remains unchanged.                                                                                                                                                                                                                                                                      |
+| `openai-orphan-item-id`                          | OpenAI, Azure OpenAI (Responses)               | Reactive API error recovery | Recovers history that OpenAI rejects with `Item 'msg_…' of type 'message' was provided without its required 'reasoning' item`. Drops the Responses `itemId` from every item-bearing part of an assistant message that carries one but has no `reasoning` part, and retries. The message then replays by value instead of as an unsatisfiable `item_reference`. The repair is applied to the in-memory list for the current turn. |
+| `anthropic-orphaned-thinking-step`               | Anthropic                                      | Reactive API error recovery | Recovers history that Anthropic rejects because `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. Removes steps that contain only reasoning when more assistant content follows them, and retries. Covers history saved by older `@mastra/memory` releases ([#22798](https://github.com/mastra-ai/mastra/issues/22798)).                                                              |
+| `ensure-user-first-turn`                         | Amazon Bedrock, Google/Vertex Gemini           | Preemptive prompt rewrite   | Inserts a minimal user turn (`.`) before a leading assistant turn, because these providers reject conversations whose first non-system turn is the assistant's. This happens when an agent greets first or `lastMessages` cuts into a thread. Runs last, so it sees the prompt after other rules have dropped emptied turns.                                                                                                     |
 
 Preemptive rules run through `processLLMRequest` after Mastra converts messages to the model prompt format and before the prompt is sent to the provider. These rewrites affect only the current provider call. Persisted history is never changed, so the IDs and content in memory and in the Studio stay exactly as written.
 

package/.docs/reference/processors/regex-filter-processor.md

@@ -108,7 +108,7 @@ const agent = new Agent({
 
 **name** (`'Regex Filter'`): Processor display name.
 
-**processInput** (`(args: ProcessInputArgs) => ProcessInputResult`): Checks input messages against all configured rules. Blocks, redacts, or warns depending on strategy. Skipped when phase is output.
+**processInput** (`(args: ProcessInputArgs) => ProcessInputResult | Promise<ProcessInputResult>`): Checks input messages against all configured rules. Blocks, redacts, or warns depending on strategy. Skipped when phase is output. Returns a promise when redaction reporting is pending.
 
 **processOutputStream** (`(args: ProcessOutputStreamArgs) => Promise<ChunkType | null | undefined>`): Checks streaming text-delta chunks against all configured rules. Skipped when phase is input.
 

package/.docs/reference/processors/system-prompt-scrubber.md

@@ -46,11 +46,11 @@ const processor = new SystemPromptScrubber({
 
 **id** (`string`): Processor identifier set to 'system-prompt-scrubber'
 
-**name** (`string`): Optional processor display name
+**name** (`string`): Processor display name, always 'System Prompt Scrubber'
 
-**processOutputStream** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<ChunkType | null>`): Processes streaming output parts to detect and handle system prompts during streaming
+**processOutputStream** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; requestContext?: RequestContext; tracingContext?: TracingContext }) => Promise<ChunkType | null>`): Processes streaming output parts to detect and handle system prompts during streaming
 
-**processOutputResult** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Processes final output results to detect and handle system prompts in non-streaming scenarios
+**processOutputResult** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; requestContext?: RequestContext; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes final output results to detect and handle system prompts in non-streaming scenarios
 
 ## Extended usage example
 

package/.docs/reference/processors/token-limiter-processor.md

@@ -28,7 +28,7 @@ const processor = new TokenLimiterProcessor({
 
 **options.limit** (`number`): Maximum number of tokens to allow in the response
 
-**options.encoding** (`TiktokenBPE`): Optional encoding to use. Defaults to o200k\_base which is used by gpt-5.1
+**options.encoding** (`unknown`): Deprecated. Accepted for backwards compatibility but ignored. Token counts are estimated with tokenx, so no encoder is needed.
 
 **options.strategy** (`'truncate' | 'abort'`): Strategy when token limit is reached: 'truncate' stops emitting chunks, 'abort' calls abort() to stop the stream
 
@@ -40,7 +40,7 @@ const processor = new TokenLimiterProcessor({
 
 **id** (`string`): Processor identifier set to 'token-limiter'
 
-**name** (`string`): Optional processor display name
+**name** (`string`): Processor display name set to 'Token Limiter'
 
 **processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Trims stored history to fit within the token limit before the agentic loop starts in 'memory-only' trim mode, prioritizing recent messages while preserving system messages and the current turn
 

package/.docs/reference/rag/graph-rag.md

@@ -83,7 +83,7 @@ Returns an array of `RankedNode` objects, where each node contains:
 
 **content** (`string`): Text content of the document chunk
 
-**metadata** (`Record<string, any>`): Additional metadata associated with the chunk
+**metadata** (`Record<string, any>`): Additional metadata associated with the chunk, when present
 
 **score** (`number`): Combined relevance score from graph traversal
 

package/.docs/reference/server/create-route.md

@@ -50,7 +50,7 @@ function createRoute<TPath, TQuery, TBody, TResponse, TResponseType>(
 
 **deprecated** (`boolean`): Mark route as deprecated
 
-**onValidationError** (`(error: ZodError, context: 'query' | 'body' | 'path') => { status: number; body: unknown } | undefined`): Custom validation error handler for this route. Overrides the server-level onValidationError hook. Return { status, body } to customize the response, or undefined to use the default.
+**onValidationError** (`(error: ZodError, context: 'query' | 'body' | 'path') => { status: number; body: unknown } | undefined | void`): Custom validation error handler for this route. Overrides the server-level onValidationError hook. Return { status, body } to customize the response, or return nothing (undefined) to use the default.
 
 ## Handler parameters
 

package/.docs/reference/server/elysia-adapter.md

@@ -61,7 +61,7 @@ console.log('Server running on http://localhost:3000')
 
 **mastra** (`Mastra`): Mastra instance
 
-**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `''`)
+**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `'/api'`)
 
 **openapiPath** (`string`): Path to serve OpenAPI spec (e.g., /openapi.json) (Default: `''`)
 

package/.docs/reference/server/express-adapter.md

@@ -60,7 +60,7 @@ Express requires `express.json()` middleware for JSON body parsing. Add it befor
 
 **mastra** (`Mastra`): Mastra instance
 
-**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `''`)
+**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `'/api'`)
 
 **openapiPath** (`string`): Path to serve OpenAPI spec (e.g., /openapi.json) (Default: `''`)
 

package/.docs/reference/server/fastify-adapter.md

@@ -63,7 +63,7 @@ app.listen({ port: 3000 }, (err, address) => {
 
 **mastra** (`Mastra`): Mastra instance
 
-**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `''`)
+**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `'/api'`)
 
 **openapiPath** (`string`): Path to serve OpenAPI spec (e.g., /openapi.json) (Default: `''`)
 

package/.docs/reference/server/hono-adapter.md

@@ -57,7 +57,7 @@ export default app
 
 **mastra** (`Mastra`): Mastra instance
 
-**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `''`)
+**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `'/api'`)
 
 **openapiPath** (`string`): Path to serve OpenAPI spec (e.g., /openapi.json) (Default: `''`)
 
@@ -142,7 +142,7 @@ Available context keys:
 | `mastra`                | Mastra instance                         |
 | `requestContext`        | Request context map                     |
 | `abortSignal`           | Request cancellation signal             |
-| `tools`                 | Available tools                         |
+| `registeredTools`       | Tools registered with the adapter       |
 | `taskStore`             | Task store for A2A operations           |
 | `customRouteAuthConfig` | Per-route auth overrides                |
 | `user`                  | Authenticated user (if auth configured) |

package/.docs/reference/server/koa-adapter.md

@@ -62,7 +62,7 @@ app.listen(3000, () => {
 
 **mastra** (`Mastra`): Mastra instance
 
-**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `''`)
+**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `'/api'`)
 
 **openapiPath** (`string`): Path to serve OpenAPI spec (e.g., /openapi.json) (Default: `''`)
 

package/.docs/reference/server/nestjs-adapter.md

@@ -89,7 +89,7 @@ By default, Mastra routes mount under `/api`. Use `prefix` to change it.
 
 **customRouteAuthConfig** (`Map<string, boolean>`): Per-route auth overrides. Keys are METHOD:PATH. Custom routes from server.apiRoutes (registerApiRoute()) are added automatically based on their requiresAuth setting.
 
-**tools** (`Record<string, Tool>`): Registered tools for the server
+**tools** (`ToolsInput`): Additional tools to register. Accepts Mastra tools, Vercel AI SDK tools, provider-defined tools, and web search tools.
 
 **taskStore** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
 

package/.docs/reference/server/routes.md

@@ -416,7 +416,7 @@ On authenticated servers, the read routes require the `stored-workflows:read` pe
 | `PATCH`  | `/api/datasets/:datasetId/experiments/:experimentId`                   | Update an experiment's name, description or metadata                                        |
 | `DELETE` | `/api/datasets/:datasetId/experiments/:experimentId`                   | Delete an experiment that belongs to the dataset                                            |
 | `GET`    | `/api/datasets/:datasetId/experiments/:experimentId/results`           | List experiment results                                                                     |
-| `POST`   | `/api/datasets/:datasetId/compare`                                     | Compare two experiments                                                                     |
+| `POST`   | `/api/datasets/:datasetId/compare`                                     | Compare two to ten experiments                                                              |
 
 ### Delete an experiment
 

package/.docs/reference/storage/composite.md

@@ -210,6 +210,40 @@ export const mastra = new Mastra({
 
 **domains.experiments** (`ExperimentsStorage`): Storage for experiment runs and per-item experiment results.
 
+**domains.workflowDefinitions** (`WorkflowDefinitionsStorage`): Storage for persisted workflow definitions.
+
+**domains.promptBlocks** (`PromptBlocksStorage`): Storage for stored prompt blocks and their versions.
+
+**domains.scorerDefinitions** (`ScorerDefinitionsStorage`): Storage for stored scorer definitions and their versions.
+
+**domains.mcpClients** (`MCPClientsStorage`): Storage for stored MCP client configurations and their versions.
+
+**domains.mcpServers** (`MCPServersStorage`): Storage for stored MCP server configurations and their versions.
+
+**domains.workspaces** (`WorkspacesStorage`): Storage for stored workspace configurations and their versions.
+
+**domains.skills** (`SkillsStorage`): Storage for stored skill definitions and their versions.
+
+**domains.favorites** (`FavoritesStorage`): Storage for user favorites on stored entities.
+
+**domains.blobs** (`BlobStore`): Content-addressable storage for file contents used by skill versioning.
+
+**domains.backgroundTasks** (`BackgroundTasksStorage`): Storage for background task state.
+
+**domains.schedules** (`SchedulesStorage`): Storage for schedules that the scheduler fires.
+
+**domains.channels** (`ChannelsStorage`): Storage for channel installations and configuration.
+
+**domains.harness** (`HarnessStorage`): Storage for harness sessions.
+
+**domains.toolProviderConnections** (`ToolProviderConnectionsStorage`): Storage for authorized tool provider connections.
+
+**domains.notifications** (`NotificationsStorage`): Storage for notifications and their delivery state.
+
+**domains.threadState** (`ThreadStateStorage`): Storage for per-thread agent state, such as task lists and goals.
+
+**domains.knowledge** (`KnowledgeStorage`): Storage for knowledge nodes and records. Experimental.
+
 ## Initialization
 
 `MastraCompositeStore` initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:

package/.docs/reference/storage/overview.md

@@ -30,7 +30,7 @@ The schema definitions below cover the built-in database-backed tables documente
 
 Stores conversation messages and their metadata. Each message belongs to a thread and contains the actual content along with metadata about the sender role and message type.
 
-iduuidv4PRIMARYKEYNOT NULLUnique identifier for the message (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)thread\_iduuidv4FK → threads.idNOT NULLParent thread referenceresourceIduuidv4CAN BE NULLID of the resource that owns this messagecontenttextNOT NULLJSON of the message content in V2 format. Example: `{ format: 2, parts: [...] }`roletextNOT NULLEnum of `user | assistant`createdAttimestampNOT NULLUsed for thread message ordering
+idtextPRIMARYKEYNOT NULLUnique identifier for the messagethread\_idtextFK → threads.idNOT NULLParent thread referenceresourceIdtextCAN BE NULLID of the resource that owns this messagecontenttextNOT NULLJSON of the message content in V2 format. Example: `{ format: 2, parts: [...] }`roletextNOT NULLEnum of `user | assistant`createdAttimestampNOT NULLUsed for thread message ordering
 
 The message `content` column contains a JSON object conforming to the `MastraMessageContentV2` type, which is designed to align closely with the AI SDK `UIMessage` message shape.
 
@@ -40,7 +40,7 @@ formatintegerNOT NULLMessage format version (currently 2)partsarray (JSON)NOT NU
 
 Groups related messages together and associates them with a resource. Contains metadata about the conversation.
 
-iduuidv4PRIMARYKEYNOT NULLUnique identifier for the thread (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)resourceIdtextNOT NULLPrimary identifier of the external resource this thread is associated with. Used to group and retrieve related threads.titletextNOT NULLTitle of the conversation threadmetadatatextCustom thread metadata as stringified JSON. Example:
+idtextPRIMARYKEYNOT NULLUnique identifier for the threadresourceIdtextNOT NULLPrimary identifier of the external resource this thread is associated with. Used to group and retrieve related threads.titletextNOT NULLTitle of the conversation threadmetadatajsonbCAN BE NULLCustom thread metadata as JSON. Example:
 
 ```json
 {
@@ -76,7 +76,7 @@ createdAttimestampNOT NULLWhen the resource record was first createdupdatedAttim
 
 When `suspend()` is called on a workflow, its state is saved in the following format. When `resume()` is called, that state is rehydrated.
 
-workflow\_nametextNOT NULLName of the workflowrun\_iduuidv4NOT NULLUnique identifier for the workflow execution. Used to track state across suspend/resume cycles (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)snapshottextNOT NULLSerialized workflow state as JSON. Example:
+workflow\_nametextNOT NULLName of the workflowrun\_idtextNOT NULLUnique identifier for the workflow execution. Used to track state across suspend/resume cyclessnapshotjsonbNOT NULLWorkflow state as JSON. Example:
 
 ```json
 {

package/.docs/reference/streaming/agents/MastraModelOutput.md

@@ -101,7 +101,7 @@ These properties resolve to final values after the stream completes:
 
 ## Error properties
 
-**error** (`string | Error | { message: string; stack: string; } | undefined`): Error information if the stream encountered an error. Undefined if no errors occurred. Can be a string message, Error object, or serialized error with stack trace.
+**error** (`Error | undefined`): Error object if the stream encountered an error. Undefined if no errors occurred.
 
 ## Methods
 

package/.docs/reference/streaming/agents/streamUntilIdle.md

@@ -66,7 +66,7 @@ Internally, `streamUntilIdle()`:
 
 1. Runs the initial turn via `agent.stream(...)` and pipes its `fullStream` into the outer stream.
 2. Subscribes to background-task completion events for the resolved memory scope.
-3. Queues each terminal event (`background-task-completed`, `background-task-failed`, `background-task-cancelled`) and, when the outer wrapper is idle between turns, re-invokes `agent.stream([], ...)` with a directive listing the completed `toolCallId`s. The continuation turn flows into the same outer stream.
+3. Queues each terminal event (`background-task-completed`, `background-task-failed`, `background-task-cancelled`, `background-task-suspended`) and, when the outer wrapper is idle between turns, re-invokes `agent.stream([], ...)` with a directive listing the completed `toolCallId`s. The continuation turn flows into the same outer stream.
 4. Closes the outer stream once no tasks are running and no completions are queued.
 
 ## Extended usage example

package/.docs/reference/streaming/workflows/timeTravelStream.md

@@ -37,14 +37,16 @@ All parameters are the same as [`Run.timeTravel()`](https://mastra.ai/reference/
 
 **output.result** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): A promise that resolves to the final workflow execution result
 
-**output.traceId** (`string`): The trace ID associated with this execution when Tracing is enabled
+**output.runId** (`string`): The ID of the workflow run
+
+**output.workflowId** (`string`): The ID of the workflow
 
 ## Stream events
 
 The stream emits workflow events during execution:
 
 - `workflow-step-start`: Emitted when a step begins execution
-- `workflow-step-finish`: Emitted when a step completes successfully
+- `workflow-step-result`: Emitted when a step produces a result
 - `workflow-step-error`: Emitted when a step encounters an error
 - `workflow-step-suspended`: Emitted when a step suspends
 - Additional events depending on step types (agents, tools, etc.)
@@ -66,8 +68,8 @@ for await (const event of output.fullStream) {
     case 'workflow-step-start':
       console.log(`Starting step: ${event.payload.stepName}`)
       break
-    case 'workflow-step-finish':
-      console.log(`Completed step: ${event.payload.stepName}`)
+    case 'workflow-step-result':
+      console.log(`Completed step: ${event.payload.id}`)
       break
     case 'workflow-step-error':
       console.error(`Error in step: ${event.payload.stepName}`, event.payload.error)

package/.docs/reference/tools/document-chunker-tool.md

@@ -20,9 +20,9 @@ const chunker = createDocumentChunkerTool({
   doc: document,
   params: {
     strategy: 'recursive',
-    size: 512,
+    maxSize: 512,
     overlap: 50,
-    separator: '\n',
+    separators: ['\n'],
   },
 })
 
@@ -39,11 +39,11 @@ const { chunks } = await chunker.execute()
 
 **strategy** (`'recursive'`): The chunking strategy to use (Default: `'recursive'`)
 
-**size** (`number`): Target size of each chunk in tokens/characters (Default: `512`)
+**maxSize** (`number`): Maximum size of each chunk in tokens/characters (Default: `512`)
 
 **overlap** (`number`): Number of overlapping tokens/characters between chunks (Default: `50`)
 
-**separator** (`string`): Character(s) to use as chunk separator (Default: `'\n'`)
+**separators** (`string[]`): Separators to split on, in order of priority (recursive strategy) (Default: `['\n']`)
 
 ## Returns
 
@@ -64,9 +64,9 @@ const chunker = createDocumentChunkerTool({
   doc: technicalDoc,
   params: {
     strategy: 'recursive',
-    size: 1024, // Larger chunks
+    maxSize: 1024, // Larger chunks
     overlap: 100, // More overlap
-    separator: '\n\n', // Split on double newlines
+    separators: ['\n\n'], // Split on double newlines
   },
 })
 
@@ -82,8 +82,8 @@ chunks.forEach((chunk, index) => {
 
 The chunker is created as a Mastra tool with the following properties:
 
-- **Tool ID**: `Document Chunker {strategy} {size}`
-- **Description**: `Chunks document using {strategy} strategy with size {size} and {overlap} overlap`
+- **Tool ID**: `Document Chunker {strategy} {maxSize}`
+- **Description**: `Chunks document using {strategy} strategy with maxSize {maxSize} and {overlap} overlap`
 - **Input Schema**: Empty object (no additional inputs required)
 - **Output Schema**: Object containing the chunks array
 

package/.docs/reference/tools/mcp-client.md

@@ -76,7 +76,7 @@ The client speaks the MCP `2026-07-28` revision. On connect it asks the server w
 
 **enableProgressTracking** (`boolean`): Whether to send a progressToken with tool calls so the server can report progress. See the progress property. (Default: `false`)
 
-**traceContext** (`() => MCPTraceContext | undefined`): Returns the W3C traceparent, optional tracestate and baggage to send as request \_meta on every call to this server. Called when each request is sent so it can read a request-local carrier. Explicit \_meta keys on a tool call take precedence. Servers built with MCPServer expose the received values to tools as requestContext.get("traceContext"); they are observability data and are never used for authorization.
+**traceContext** (`() => MCPTraceContext | undefined`): Returns the W3C traceparent, optional tracestate and baggage to send as request \_meta on every call to this server. Called when each request is sent so it can read a request-local carrier. Without this option, a tool call made by a traced agent or workflow sends the traceparent of its tool call span. When the reply names the server span that handled the call, as MCPServer does, the tool call span links to it. Set this option to send your own trace context, or return undefined to send none. Explicit \_meta keys on a tool call take precedence. Servers built with MCPServer link their request span to the span the traceparent names and expose the received values to tools as requestContext.get("traceContext"); they are observability data and are never used for authorization.
 
 **forwardInstructions** (`boolean`): Whether to append instructions advertised by this MCP server to an agent's system prompt when the agent uses this server's tools. Disabled by default; enable it only for servers you trust, since the instructions are injected into the agent's system prompt. (Default: `false`)
 

package/.docs/reference/tools/mcp-server.md

@@ -856,6 +856,23 @@ The span is named after the method and target (for example `tools/call lookupOrd
 
 A standalone `MCPServer` with no `mastra` instance produces no spans.
 
+### Linking to the caller's trace
+
+A request that carries a W3C `traceparent` keeps its own trace, root span, and trace summary. Its request span links to the caller's span, so you can follow a tool call from the caller's trace to the request it started.
+
+With a tracing bridge, the request span starts under the span that's active when the request arrives. If HTTP instrumentation on the server continues the caller's trace from the `traceparent` header, the request joins the caller's trace instead of starting its own. Its link then points to a span in the same trace.
+
+The server reads `traceparent` and `tracestate` from two places, in this order:
+
+1. The request `_meta`. `MCPClient` sends `traceparent` there for every traced tool call an agent or workflow makes, over HTTP and stdio.
+2. The HTTP headers. OpenTelemetry HTTP instrumentation in a non-Mastra caller sends them there.
+
+The request span also records a valid `traceparent` as the `callerTraceparent` attribute, and the `tracestate` sent with it as `callerTracestate`, capped at 512 characters. Exporters without span link support still carry these attributes. A request without a valid `traceparent` gets no link and no caller attributes. The trace fields are left out of the span input.
+
+The link also works in the other direction. When a `tools/call` request carried a `traceparent`, the reply's `_meta.mastra.traceparent` names the request span, and `MCPClient` adds a link from its tool call span to it. Callers that sent no trace context get nothing back.
+
+Mastra storage saves the links with the spans. The OpenTelemetry exporter, [`OtelBridge`](https://mastra.ai/integrations/observability/opentelemetry), `DatadogBridge`, `DatadogExporter`, and `SentryExporter` send them as span links. `DatadogExporter` and `SentryExporter` give spans their own IDs, so a link between two Mastra spans doesn't resolve in those backends.
+
 ## Notification delivery
 
 Request-scoped notifications (`context.mcp.log()`, `context.mcp.progress()`) stream inside the request that triggered them, so they reach exactly the caller. Notifications that outlive a request (`resources.notifyListChanged()`, `prompts.notifyListChanged()`, `toolActions.notifyListChanged()`, `resources.notifyUpdated()`) are delivered on the `subscriptions/listen` stream each interested client keeps open. `resources.notifyUpdated()` only reaches clients whose stream includes that resource URI. List-changed notifications reach every client listening for that list. Over stdio the connection itself carries the stream.

package/.docs/reference/tools/submit-plan-tool.md

@@ -66,6 +66,8 @@ The model calls this tool with the following parameters:
 
 The `tool-call-suspended` event carries a `suspendPayload`:
 
+**toolId** (`'submit_plan'`): ID of the tool that suspended the run.
+
 **path** (`string`): Path to the plan file the agent wrote.
 
 **title** (`string`): Plan title, filled by the host after reading the file.

package/.docs/reference/tools/vector-query-tool.md

@@ -21,13 +21,13 @@ const queryTool = createVectorQueryTool({
 
 ## Parameters
 
-> **Note:** **Parameter Requirements:** Most fields can be set at creation as defaults. Some fields can be overridden at runtime via the request context or input. If a required field is missing from both creation and runtime, an error will be thrown. Note that `model`, `id`, and `description` can only be set at creation time.
+> **Note:** **Parameter Requirements:** Most fields can be set at creation as defaults. Some fields can be overridden at runtime via the request context or input. If a required field is missing from both creation and runtime, an error will be thrown. Note that `id` and `description` can only be set at creation time.
 
-**id** (`string`): Custom ID for the tool. By default: 'VectorQuery {vectorStoreName} {indexName} Tool'. (Set at creation only.)
+**id** (`string`): Custom ID for the tool. By default: 'VectorQuery {vectorStoreName} {indexName} Tool', where {vectorStoreName} is 'DirectVectorStore' when a vectorStore instance is passed without a vectorStoreName. (Set at creation only.)
 
 **description** (`string`): Custom description for the tool. By default: 'Access the knowledge base to find information needed to answer user questions' (Set at creation only.)
 
-**model** (`EmbeddingModel`): Embedding model to use for vector search. (Set at creation only.)
+**model** (`EmbeddingModel`): Embedding model to use for vector search. (Can be set at creation or overridden at runtime via the request context.)
 
 **vectorStoreName** (`string`): Name of the vector store to query. (Can be set at creation or overridden at runtime.)
 
@@ -47,7 +47,7 @@ const queryTool = createVectorQueryTool({
 
 **reranker.options.weights** (`WeightConfig`): Weights for scoring components (semantic: 0.4, vector: 0.4, position: 0.2)
 
-**reranker.options.topK** (`number`): Number of top results to return
+**reranker.options.topK** (`number`): Number of top results to return after reranking. Falls back to the query's topK (from the request context, the tool input, or 10) when unset or 0.
 
 **databaseConfig** (`DatabaseConfig`): Database-specific configuration options for optimizing queries. (Can be set at creation or overridden at runtime.)
 

package/.docs/reference/vectors/astra.md

@@ -110,7 +110,7 @@ try {
   })
 } catch (error) {
   if (error instanceof MastraError) {
-    console.log(error.id) // 'MASTRA_VECTOR_ASTRA_QUERY_FAILED'
+    console.log(error.id) // 'MASTRA_VECTOR_ASTRA_QUERY_DB_ERROR'
     console.log(error.domain) // 'MASTRA_VECTOR'
     console.log(error.category) // 'USER' | 'THIRD_PARTY'
     console.log(error.details) // Additional error context

package/.docs/reference/vectors/azure-ai-search.md

@@ -141,6 +141,7 @@ interface QueryResult {
   id: string
   score: number
   metadata: Record<string, any>
+  document?: string // Matched document content
   vector?: number[] // Only included if includeVector is true
 }
 ```

package/.docs/reference/vectors/chroma.md

@@ -86,7 +86,7 @@ Query an index using a `queryVector`. Returns an array of semantically similar r
   score: number;
   document?: string;
   metadata?: Record<string, string | number | boolean>;
-  embedding?: number[]
+  vector?: number[] // Only included if includeVector is true
 }
 ```
 
@@ -147,7 +147,7 @@ Returns:
 interface IndexStats {
   dimension: number
   count: number
-  metric: 'cosine' | 'euclidean' | 'dotproduct'
+  metric?: 'cosine' | 'euclidean' | 'dotproduct'
 }
 ```
 
@@ -247,17 +247,21 @@ interface QueryResult {
 
 ## Error handling
 
-The store throws typed errors that can be caught:
+The store throws `MastraError` instances from `@mastra/core/error`:
 
 ```typescript
+import { MastraError } from '@mastra/core/error'
+
 try {
   await store.query({
     indexName: 'index_name',
     queryVector: queryVector,
   })
 } catch (error) {
-  if (error instanceof VectorStoreError) {
-    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
+  if (error instanceof MastraError) {
+    console.log(error.id) // 'MASTRA_VECTOR_CHROMA_QUERY_FAILED'
+    console.log(error.domain) // 'MASTRA_VECTOR'
+    console.log(error.category) // 'USER' | 'THIRD_PARTY'
     console.log(error.details) // Additional error context
   }
 }