@mastra/mcp-docs-server 1.1.39-alpha.8 → 1.1.39

package/.docs/models/providers/routing-run.md

@@ -1,6 +1,6 @@
 # ![routing.run logo](https://models.dev/logos/routing-run.svg)routing.run
 
-Access 37 routing.run models through Mastra's model router. Authentication is handled automatically using the `ROUTING_RUN_API_KEY` environment variable.
+Access 24 routing.run models through Mastra's model router. Authentication is handled automatically using the `ROUTING_RUN_API_KEY` environment variable.
 
 Learn more in the [routing.run documentation](https://docs.routing.run).
 
@@ -32,45 +32,32 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model                                         | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| --------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `routing-run/route/deepseek-v3.2`             | 164K    |       |           |       |       |       | $0.49      | $0.74       |
-| `routing-run/route/deepseek-v4-flash`         | 1.0M    |       |           |       |       |       | $0.49      | $0.74       |
-| `routing-run/route/deepseek-v4-flash-full`    | 1.0M    |       |           |       |       |       | $0.49      | $0.74       |
-| `routing-run/route/deepseek-v4-pro`           | 1.0M    |       |           |       |       |       | $0.49      | $0.74       |
-| `routing-run/route/deepseek-v4-pro-precision` | 1.0M    |       |           |       |       |       | $0.74      | $1          |
-| `routing-run/route/gemma-4-31b-it`            | 131K    |       |           |       |       |       | $0.10      | $0.30       |
-| `routing-run/route/glm-4.7`                   | 128K    |       |           |       |       |       | $1         | $4          |
-| `routing-run/route/glm-4.7-flash`             | 128K    |       |           |       |       |       | $1         | $4          |
-| `routing-run/route/glm-5`                     | 203K    |       |           |       |       |       | $0.79      | $3          |
-| `routing-run/route/glm-5-highspeed`           | 203K    |       |           |       |       |       | $1         | $4          |
-| `routing-run/route/glm-5.1`                   | 203K    |       |           |       |       |       | $1         | $3          |
-| `routing-run/route/glm-5.1-fp16`              | 203K    |       |           |       |       |       | $1         | $4          |
-| `routing-run/route/glm-5.1-full`              | 203K    |       |           |       |       |       | $1         | $4          |
-| `routing-run/route/glm-5.1-precision`         | 203K    |       |           |       |       |       | $1         | $4          |
-| `routing-run/route/kimi-k2.5`                 | 262K    |       |           |       |       |       | $0.46      | $2          |
-| `routing-run/route/kimi-k2.5-highspeed`       | 131K    |       |           |       |       |       | $0.65      | $3          |
-| `routing-run/route/kimi-k2.6`                 | 262K    |       |           |       |       |       | $0.46      | $2          |
-| `routing-run/route/kimi-k2.6-full`            | 262K    |       |           |       |       |       | $0.46      | $2          |
-| `routing-run/route/kimi-k2.6-precision`       | 262K    |       |           |       |       |       | $0.65      | $3          |
-| `routing-run/route/mimo-v2.5`                 | 256K    |       |           |       |       |       | $0.40      | $2          |
-| `routing-run/route/mimo-v2.5-pro`             | 1.0M    |       |           |       |       |       | $0.45      | $1          |
-| `routing-run/route/mimo-v2.5-pro-precision`   | 1.0M    |       |           |       |       |       | $0.45      | $1          |
-| `routing-run/route/minimax-m2.5`              | 100K    |       |           |       |       |       | $0.19      | $1          |
-| `routing-run/route/minimax-m2.5-highspeed`    | 100K    |       |           |       |       |       | $0.19      | $1          |
-| `routing-run/route/minimax-m2.7`              | 100K    |       |           |       |       |       | $0.33      | $1          |
-| `routing-run/route/minimax-m2.7-highspeed`    | 100K    |       |           |       |       |       | $0.33      | $1          |
-| `routing-run/route/mistral-large-3`           | 128K    |       |           |       |       |       | $0.50      | $2          |
-| `routing-run/route/mistral-medium-2505`       | 128K    |       |           |       |       |       | $0.40      | $2          |
-| `routing-run/route/mistral-small-2503`        | 128K    |       |           |       |       |       | $0.15      | $0.60       |
-| `routing-run/route/qwen3.5-397b-a17b`         | 262K    |       |           |       |       |       | $1         | $3          |
-| `routing-run/route/qwen3.5-9b`                | 262K    |       |           |       |       |       | $0.20      | $0.60       |
-| `routing-run/route/qwen3.5-9b-chat`           | 262K    |       |           |       |       |       | $0.20      | $0.60       |
-| `routing-run/route/qwen3.6-27b`               | 262K    |       |           |       |       |       | $1         | $3          |
-| `routing-run/route/step-3.5-flash`            | 262K    |       |           |       |       |       | $0.10      | $0.29       |
-| `routing-run/route/step-3.5-flash-2603`       | 262K    |       |           |       |       |       | $0.10      | $0.30       |
-| `routing-run/route/step-3.5-flash-full`       | 262K    |       |           |       |       |       | $0.10      | $0.29       |
-| `routing-run/route/stepfun-3.5-flash`         | 262K    |       |           |       |       |       | $0.10      | $0.29       |
+| Model                                      | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ------------------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `routing-run/route/deepseek-v3.2`          | 164K    |       |           |       |       |       | $0.49      | $0.74       |
+| `routing-run/route/deepseek-v4-flash`      | 1.0M    |       |           |       |       |       | $0.49      | $0.74       |
+| `routing-run/route/deepseek-v4-flash-6bit` | 1.0M    |       |           |       |       |       | $0.49      | $0.74       |
+| `routing-run/route/deepseek-v4-pro`        | 1.0M    |       |           |       |       |       | $0.49      | $0.74       |
+| `routing-run/route/deepseek-v4-pro-6bit`   | 1.0M    |       |           |       |       |       | $0.49      | $0.74       |
+| `routing-run/route/gemma-4-31b-it`         | 131K    |       |           |       |       |       | $0.10      | $0.30       |
+| `routing-run/route/glm-5.1`                | 203K    |       |           |       |       |       | $1         | $3          |
+| `routing-run/route/glm-5.1-6bit`           | 203K    |       |           |       |       |       | $1         | $3          |
+| `routing-run/route/kimi-k2.5`              | 131K    |       |           |       |       |       | $0.46      | $2          |
+| `routing-run/route/kimi-k2.6`              | 262K    |       |           |       |       |       | $0.46      | $2          |
+| `routing-run/route/kimi-k2.6-6bit`         | 262K    |       |           |       |       |       | $0.46      | $2          |
+| `routing-run/route/mimo-v2.5-pro`          | 1.0M    |       |           |       |       |       | $0.45      | $1          |
+| `routing-run/route/mimo-v2.5-pro-6bit`     | 1.0M    |       |           |       |       |       | $0.45      | $1          |
+| `routing-run/route/minimax-m2.5`           | 100K    |       |           |       |       |       | $0.19      | $1          |
+| `routing-run/route/minimax-m2.5-highspeed` | 100K    |       |           |       |       |       | $0.19      | $1          |
+| `routing-run/route/minimax-m2.7`           | 100K    |       |           |       |       |       | $0.33      | $1          |
+| `routing-run/route/minimax-m2.7-highspeed` | 100K    |       |           |       |       |       | $0.33      | $1          |
+| `routing-run/route/mistral-large-3`        | 128K    |       |           |       |       |       | $0.50      | $2          |
+| `routing-run/route/mistral-medium-2505`    | 128K    |       |           |       |       |       | $0.40      | $2          |
+| `routing-run/route/mistral-small-2503`     | 128K    |       |           |       |       |       | $0.15      | $0.60       |
+| `routing-run/route/qwen3.6-27b`            | 262K    |       |           |       |       |       | $1         | $3          |
+| `routing-run/route/step-3.5-flash`         | 262K    |       |           |       |       |       | $0.10      | $0.29       |
+| `routing-run/route/step-3.5-flash-2603`    | 262K    |       |           |       |       |       | $0.10      | $0.30       |
+| `routing-run/route/stepfun-3.5-flash`      | 262K    |       |           |       |       |       | $0.10      | $0.29       |
 
 ## Advanced configuration
 

package/.docs/models/providers/the-grid-ai.md

@@ -1,6 +1,6 @@
 # ![The Grid AI logo](https://models.dev/logos/the-grid-ai.svg)The Grid AI
 
-Access 3 The Grid AI models through Mastra's model router. Authentication is handled automatically using the `THEGRIDAI_API_KEY` environment variable.
+Access 9 The Grid AI models through Mastra's model router. Authentication is handled automatically using the `THEGRIDAI_API_KEY` environment variable.
 
 Learn more in the [The Grid AI documentation](https://thegrid.ai/docs).
 
@@ -15,7 +15,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "the-grid-ai/text-max"
+  model: "the-grid-ai/agent-max"
 });
 
 // Generate a response
@@ -32,11 +32,17 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model                       | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| --------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `the-grid-ai/text-max`      | 1.0M    |       |           |       |       |       | —          | —           |
-| `the-grid-ai/text-prime`    | 128K    |       |           |       |       |       | —          | —           |
-| `the-grid-ai/text-standard` | 128K    |       |           |       |       |       | —          | —           |
+| Model                        | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ---------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `the-grid-ai/agent-max`      | 1.0M    |       |           |       |       |       | —          | —           |
+| `the-grid-ai/agent-prime`    | 128K    |       |           |       |       |       | —          | —           |
+| `the-grid-ai/agent-standard` | 128K    |       |           |       |       |       | —          | —           |
+| `the-grid-ai/code-max`       | 1.0M    |       |           |       |       |       | —          | —           |
+| `the-grid-ai/code-prime`     | 128K    |       |           |       |       |       | —          | —           |
+| `the-grid-ai/code-standard`  | 128K    |       |           |       |       |       | —          | —           |
+| `the-grid-ai/text-max`       | 1.0M    |       |           |       |       |       | —          | —           |
+| `the-grid-ai/text-prime`     | 128K    |       |           |       |       |       | —          | —           |
+| `the-grid-ai/text-standard`  | 128K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -48,7 +54,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://api.thegrid.ai/v1",
-    id: "the-grid-ai/text-max",
+    id: "the-grid-ai/agent-max",
     apiKey: process.env.THEGRIDAI_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -67,7 +73,7 @@ const agent = new Agent({
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
       ? "the-grid-ai/text-standard"
-      : "the-grid-ai/text-max";
+      : "the-grid-ai/agent-max";
   }
 });
 ```

package/.docs/models/providers/xai.md

@@ -1,6 +1,6 @@
 # ![xAI logo](https://models.dev/logos/xai.svg)xAI
 
-Access 15 xAI models through Mastra's model router. Authentication is handled automatically using the `XAI_API_KEY` environment variable.
+Access 16 xAI models through Mastra's model router. Authentication is handled automatically using the `XAI_API_KEY` environment variable.
 
 Learn more in the [xAI documentation](https://docs.x.ai/docs/models).
 
@@ -43,6 +43,7 @@ for await (const chunk of stream) {
 | `xai/grok-4.20-multi-agent-0309`   | 2.0M    |       |           |       |       |       | $2         | $6          |
 | `xai/grok-4.3`                     | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `xai/grok-beta`                    | 131K    |       |           |       |       |       | $5         | $15         |
+| `xai/grok-build-0.1`               | 256K    |       |           |       |       |       | $1         | $2          |
 | `xai/grok-imagine-image`           | 1K      |       |           |       |       |       | —          | —           |
 | `xai/grok-imagine-image-quality`   | 1K      |       |           |       |       |       | —          | —           |
 | `xai/grok-imagine-video`           | 1K      |       |           |       |       |       | —          | —           |

package/.docs/reference/agents/agent.md

@@ -126,24 +126,32 @@ agent.sendSignal(
 )
 ```
 
-Use a custom signal type for contextual messages that should reach the model as XML-wrapped context instead of normal user input:
+Use `attributes` to identify different users in a shared thread. The signal type and attributes are rendered as XML so the model can distinguish who said what:
 
 ```typescript
 agent.sendSignal(
   {
-    type: 'system-reminder',
-    contents: 'Continue from the previous tool result.',
-    attributes: { reminderType: 'tool-result' },
+    type: 'user',
+    contents: 'Can we simplify the API surface?',
+    attributes: { name: 'Devin', from: 'slack' },
   },
   { resourceId: 'user-123', threadId: 'thread-abc' },
 )
 ```
 
+The model receives this as:
+
+```xml
+<user name="Devin" from="slack">Can we simplify the API surface?</user>
+```
+
+The UI sees just the message contents but can also read `attributes` and `metadata` off the signal message for custom rendering (e.g. showing user names, avatars, or platform badges).
+
 ### `sendSignal(signal, options)`
 
 Sends a signal to an active run or memory thread.
 
-**signal** (`{ type: 'user-message' | string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): \`user-message\` signals are treated as user input. Other signal types are wrapped in XML context (with any \`attributes\`) before the next model call. \`providerOptions\` is attached to the resulting prompt turn and persisted on the stored signal message.
+**signal** (`{ type: 'user-message' | 'system-reminder' | string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): \`user-message\` signals without attributes are treated as plain user input. All other signals — including \`user-message\` with \`attributes\`, \`system-reminder\`, and custom types — are wrapped in an XML element named after the signal type with \`attributes\` rendered as XML attributes (e.g. \`\<user name="Devin" from="slack">message\</user>\`). The model sees the XML; the UI sees the raw contents and can read \`attributes\` for custom rendering. \`providerOptions\` is attached to the resulting prompt turn and persisted on the stored signal message.
 
 **options.runId** (`string`): Run ID to target directly. Use this when you already know the active run ID.
 

package/.docs/reference/agents/channels.md

@@ -31,7 +31,7 @@ export const supportAgent = new Agent({
 
 **handlers** (`ChannelHandlers`): Override default message handlers for DMs, mentions, and subscribed threads.
 
-**inlineMedia** (`string[] | ((mimeType: string) => boolean)`): Controls which attachment types are sent as file parts to the model. Types that do not match are described as text summaries. Accepts an array of mime type globs or a predicate function. (Default: `['image/*']`)
+**inlineMedia** (`string[] | ((mimeType: string) => boolean)`): Controls which attachment types are sent as file parts to the model. Types that do not match are described as text summaries. Accepts an array of mime type globs or a predicate function. The default matches the formats supported by major vision models. (Default: `['image/png', 'image/jpeg', 'image/webp', 'application/pdf']`)
 
 **inlineLinks** (`InlineLinkEntry[]`): Promote URLs found in message text to file parts so the model can process linked content. Each entry matches a domain. Disabled by default.
 
@@ -91,7 +91,7 @@ const agent = new Agent({
 
 Override built-in event handlers. Each handler can be:
 
-- **Omitted**: uses the default Mastra handler (routes to `agent.stream` and posts the response)
+- **Omitted**: uses the default Mastra handler (routes the message through the agent and posts the response)
 - **`false`**: disables the handler entirely
 - **A function** `(thread, message, defaultHandler) => Promise<void>`: wraps or replaces the default
 
@@ -138,6 +138,8 @@ type ChannelHandler = (
 
 Controls which attachment types (images, video, PDFs, etc.) are sent as file parts to the model. Types that do not match are described as text summaries so the agent knows about the file without crashing models that reject unsupported types.
 
+The default (`['image/png', 'image/jpeg', 'image/webp', 'application/pdf']`) matches the formats supported by major vision models. Override `inlineMedia` to expand the list (e.g. `['image/*', 'audio/*']`) or replace it entirely with a predicate function.
+
 Supported glob patterns:
 
 | Pattern           | Matches                                           |

package/.docs/reference/client-js/agents.md

@@ -201,7 +201,7 @@ await agent.sendSignal({
 
 Returns `{ accepted: true, runId: string }`.
 
-**signal** (`{ type: 'user-message' | string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): \`user-message\` signals are treated as user input. Other signal types are wrapped in XML context (with any \`attributes\`) before the next model call. \`providerOptions\` is attached to the resulting prompt turn and persisted on the stored signal message.
+**signal** (`{ type: 'user-message' | 'system-reminder' | string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): \`user-message\` signals without attributes are treated as plain user input. All other signals — including \`user-message\` with \`attributes\`, \`system-reminder\`, and custom types — are wrapped in an XML element named after the signal type with \`attributes\` rendered as XML attributes (e.g. \`\<user name="Devin" from="slack">message\</user>\`). The model sees the XML; the UI sees the raw contents and can read \`attributes\` for custom rendering. \`providerOptions\` is attached to the resulting prompt turn and persisted on the stored signal message.
 
 **runId** (`string`): Run ID to target directly.
 

package/.docs/reference/configuration.md

@@ -63,7 +63,7 @@ export const mastra = new Mastra({
 })
 ```
 
-**enabled** (`boolean`): Whether background tasks are enabled. The manager only initializes when this is true and a storage backend is configured. (Default: `false`)
+**enabled** (`boolean`): Whether the background task manager is available. The manager only initializes when this is true and a storage backend is configured. This is a feature-availability switch — it does not opt any tool into background dispatch. Tools must opt in at the tool or agent layer (see the Background tasks guide). (Default: `false`)
 
 **globalConcurrency** (`number`): Maximum number of background tasks running concurrently across all agents. (Default: `10`)
 

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

@@ -36,7 +36,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **scope** (`'resource' | 'thread'`): Memory scope for observations. \`'thread'\` keeps observations per-thread. \`'resource'\` (experimental) shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
 
-**activateAfterIdle** (`number | string | false`): Time before buffered observations are forced to activate after inactivity, even before \`observation.messageTokens\` is reached. Accepts a numeric millisecond value such as \`300\_000\`, duration strings like \`"5m"\` or \`"1hr"\`, or \`false\` to disable inherited observation idle activation. Reflections do not inherit this setting. Use \`reflection.activateAfterIdle\` to opt reflections into idle activation.
+**activateAfterIdle** (`number | string | false | "auto"`): Time before buffered observations are forced to activate after inactivity, even before \`observation.messageTokens\` is reached. Accepts a numeric millisecond value such as \`300\_000\`, duration strings like \`"5m"\` or \`"1hr"\`, \`"auto"\` for a provider-aware prompt cache TTL, or \`false\` to disable inherited observation idle activation. Reflections do not inherit this setting. Use \`reflection.activateAfterIdle\` to opt reflections into idle activation.
 
 **activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. Reflections do not inherit this setting. Use \`reflection.activateOnProviderChange\` to opt reflections into provider-change activation. (Default: `false`)
 
@@ -54,6 +54,8 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.threadTitle** (`boolean`): When \`true\`, the Observer suggests short thread titles and updates the thread title when the conversation topic meaningfully changes. This is opt-in and defaults to disabled.
 
+**observation.observeAttachments** (`boolean | string[]`): Controls which image/file attachments are forwarded to the Observer model alongside their placeholder text lines. \`true\` (default) forwards all attachments. \`false\` drops all attachments while keeping placeholders visible. An array is a case-insensitive mimeType allowlist supporting exact matches (\`'application/pdf'\`), wildcard subtypes (\`'image/\*'\`), and bare \`'\*'\` for everything. Useful when the Observer model is text-only (e.g. some DeepSeek endpoints) while the main agent uses a multimodal model. Tool-result attachments are filtered using the same rule.
+
 **observation.messageTokens** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called. Text is estimated locally with \`tokenx\`. Image parts are included with model-aware heuristics when possible, with deterministic fallbacks when image metadata is incomplete. Image-like \`file\` parts are counted the same way when uploads are normalized as files.
 
 **observation.maxTokensPerBatch** (`number`): Maximum tokens per batch when observing multiple threads in resource scope. Threads are chunked into batches of this size and processed in parallel. Lower values mean more parallelism but more API calls.
@@ -68,7 +70,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.bufferActivation** (`number`): Controls how much of the message window to retain after activation. Accepts a ratio (0-1) or an absolute token count (≥ 1000). For example, \`0.8\` means: activate enough buffers to remove 80% of \`messageTokens\` and leave 20% as active message history. An absolute token count like \`4000\` targets a goal of keeping \~4k message tokens remaining after activation. Higher values remove more message history per activation when using a ratio. Higher values keep more message history when using a token count.
 
-**observation.activateAfterIdle** (`number | string | false`): Time before buffered observations are forced to activate after inactivity. Accepts milliseconds, a duration string, or \`false\`. If unset, the top-level \`activateAfterIdle\` value is used for observations. Set \`false\` to disable the top-level idle setting for observations.
+**observation.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered observations are forced to activate after inactivity. Accepts milliseconds, a duration string, \`"auto"\` for a provider-aware prompt cache TTL, or \`false\`. If unset, the top-level \`activateAfterIdle\` value is used for observations. Set \`false\` to disable the top-level idle setting for observations.
 
 **observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level \`activateOnProviderChange\` value is used for observations.
 
@@ -92,7 +94,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **reflection.bufferActivation** (`number`): Ratio (0-1) controlling when async reflection buffering starts. When observation tokens reach \`observationTokens \* bufferActivation\`, reflection runs in the background. On activation at the full threshold, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range.
 
-**reflection.activateAfterIdle** (`number | string | false`): Time before buffered reflections are forced to activate after inactivity. Accepts milliseconds, a duration string, or \`false\`. Reflections do not inherit top-level \`activateAfterIdle\`; set this explicitly to opt reflections into idle activation.
+**reflection.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered reflections are forced to activate after inactivity. Accepts milliseconds, a duration string, \`"auto"\` for a provider-aware prompt cache TTL, or \`false\`. Reflections do not inherit top-level \`activateAfterIdle\`; set this explicitly to opt reflections into idle activation.
 
 **reflection.activateOnProviderChange** (`boolean`): Force buffered reflections to activate when the actor provider or model changes. Reflections do not inherit top-level \`activateOnProviderChange\`; set this explicitly to opt reflections into provider-change activation.
 

package/.docs/reference/server/register-api-route.md

@@ -18,7 +18,7 @@ The URL path for the route. Supports path parameters using `:param` syntax.
 registerApiRoute("/items/:itemId", { ... })
 ```
 
-**Note:** Paths can't start with `/api/` as this prefix is reserved for Mastra server routes.
+**Note:** Custom route paths can't start with the server's configured `apiPrefix` (default: `/api`), as that prefix is reserved for built-in Mastra routes. If you set a custom `apiPrefix`, only that prefix is reserved — for example, with `apiPrefix: '/mastra/api'`, paths like `/api/my-endpoint` are allowed.
 
 ### options
 

package/.docs/reference/storage/convex.md

@@ -34,7 +34,7 @@ bun add @mastra/convex@latest
 
 ## Convex setup
 
-Before using `ConvexStore`, you need to set up the Convex schema and storage handler in your Convex project.
+Before using `ConvexStore`, set up the Convex schema and storage handler in your Convex project. The schema example below includes the full `ConvexStore` and `ConvexServerCache` setup. If you only use `ConvexStore`, omit `mastraCacheTable` and `mastraCacheListItemsTable`; if you use `ConvexServerCache`, include those tables and create the cache handler.
 
 ### 1. Set up Convex Schema
 
@@ -50,6 +50,8 @@ import {
   mastraScoresTable,
   mastraVectorIndexesTable,
   mastraVectorsTable,
+  mastraCacheTable,
+  mastraCacheListItemsTable,
   mastraDocumentsTable,
 } from '@mastra/convex/schema'
 
@@ -61,6 +63,8 @@ export default defineSchema({
   mastra_scorers: mastraScoresTable,
   mastra_vector_indexes: mastraVectorIndexesTable,
   mastra_vectors: mastraVectorsTable,
+  mastra_cache: mastraCacheTable,
+  mastra_cache_list_items: mastraCacheListItemsTable,
   mastra_documents: mastraDocumentsTable,
 })
 ```
@@ -75,6 +79,14 @@ import { mastraStorage } from '@mastra/convex/server'
 export const handle = mastraStorage
 ```
 
+If you use `ConvexServerCache`, create `convex/mastra/cache.ts`:
+
+```typescript
+import { mastraCache } from '@mastra/convex/server'
+
+export const handle = mastraCache
+```
+
 ### 3. Deploy to Convex
 
 ```bash
@@ -86,16 +98,21 @@ npx convex deploy
 ## Usage
 
 ```typescript
-import { ConvexStore } from '@mastra/convex'
+import { ConvexServerCache, ConvexStore } from '@mastra/convex'
 
 const storage = new ConvexStore({
   id: 'convex-storage',
   deploymentUrl: process.env.CONVEX_URL!,
   adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
 })
+
+const cache = new ConvexServerCache({
+  deploymentUrl: process.env.CONVEX_URL!,
+  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
+})
 ```
 
-## Parameters
+## ConvexStore parameters
 
 **deploymentUrl** (`string`): Convex deployment URL (e.g., https\://your-project.convex.cloud)
 
@@ -103,10 +120,24 @@ const storage = new ConvexStore({
 
 **storageFunction** (`string`): Path to the storage mutation function (default: 'mastra/storage:handle') (Default: `mastra/storage:handle`)
 
+## ConvexServerCache parameters
+
+**deploymentUrl** (`string`): Convex deployment URL (e.g., https\://your-project.convex.cloud)
+
+**adminAuthToken** (`string`): Convex admin authentication token for backend access
+
+**cacheFunction** (`string`): Path to the cache mutation function for ConvexServerCache (default: 'mastra/cache:handle') (Default: `mastra/cache:handle`)
+
+**requestTimeoutMs** (`number`): Timeout for Convex cache mutation requests in milliseconds. Set to 0 to disable the client-side timeout. (Default: `30000`)
+
+**keyPrefix** (`string`): Prefix applied to ConvexServerCache keys. clear() removes rows whose stored prefix exactly matches this value. (Default: `mastra:cache:`)
+
+**ttlMs** (`number`): Default ConvexServerCache TTL in milliseconds. Set to 0 to disable expiry. (Default: `300000`)
+
 ## Constructor examples
 
 ```ts
-import { ConvexStore } from '@mastra/convex'
+import { ConvexServerCache, ConvexStore } from '@mastra/convex'
 
 // Basic configuration
 const store = new ConvexStore({
@@ -122,22 +153,53 @@ const storeCustom = new ConvexStore({
   adminAuthToken: 'your-admin-token',
   storageFunction: 'custom/path:handler',
 })
+
+// Server cache for durable stream replay and response caching
+const cache = new ConvexServerCache({
+  deploymentUrl: 'https://your-project.convex.cloud',
+  adminAuthToken: 'your-admin-token',
+  cacheFunction: 'mastra/cache:handle',
+})
 ```
 
+## Server cache
+
+`ConvexServerCache` implements Mastra's server cache contract with Convex. Use it when you want durable cache state for features such as resumable durable-agent streams, workflow stream replay, or response caching.
+
+`ConvexServerCache` stores list entries as separate Convex documents. This avoids growing a stream replay list inside one document and helps stay within Convex's record size limit.
+
+Each scalar cache value and each list item is stored as one Convex row and must stay within Convex's row-size limits. Very large lists are still bounded by Convex query limits when replaying a range.
+
+Cache cleanup and `clear()` run in bounded batches. A single client call can loop through up to 1,000 Convex mutations, with each mutation handling up to 25 list items. While `clear()` is cleaning a key, reads for that key can return empty results until cleanup finishes.
+
+For very large cache namespaces, clear incrementally or use narrower prefixes to avoid long-running cleanup operations.
+
+During batched cleanup, cache metadata can temporarily use an internal `deleted` state. The next cleanup pass removes those rows. Avoid writing new values with the same prefix until `clear()` finishes.
+
+`clear()` only removes rows whose stored `keyPrefix` exactly matches the configured `keyPrefix`. It does not clear nested prefixes by string prefix matching. Each `listPush()` refreshes the list TTL using the cache's configured `ttlMs`.
+
+Use a non-empty `keyPrefix` unless you intentionally want `clear()` to remove every cache key in the deployment. Expired list rows are reclaimed incrementally during reads and writes; `clear()` removes all rows for the prefix.
+
+`ConvexServerCache` works best for durable replay of moderate-frequency events. For high-frequency token streams, prefer batching events or using a lower-latency cache backend.
+
+`ConvexServerCache` does not replace a distributed pub/sub transport. If your app needs live cross-process event delivery, configure a production pub/sub backend separately.
+
 ## Additional notes
 
 ### Schema Management
 
 The storage implementation uses typed Convex tables for each Mastra domain:
 
-| Domain    | Convex Table                | Purpose              |
-| --------- | --------------------------- | -------------------- |
-| Threads   | `mastra_threads`            | Conversation threads |
-| Messages  | `mastra_messages`           | Chat messages        |
-| Resources | `mastra_resources`          | User working memory  |
-| Workflows | `mastra_workflow_snapshots` | Workflow state       |
-| Scorers   | `mastra_scorers`            | Evaluation data      |
-| Fallback  | `mastra_documents`          | Unknown tables       |
+| Domain      | Convex Table                | Purpose                                   |
+| ----------- | --------------------------- | ----------------------------------------- |
+| Threads     | `mastra_threads`            | Conversation threads                      |
+| Messages    | `mastra_messages`           | Chat messages                             |
+| Resources   | `mastra_resources`          | User working memory                       |
+| Workflows   | `mastra_workflow_snapshots` | Workflow state                            |
+| Scorers     | `mastra_scorers`            | Evaluation data                           |
+| Cache       | `mastra_cache`              | Cache values, counters, and list metadata |
+| Cache Items | `mastra_cache_list_items`   | Cache list entries                        |
+| Fallback    | `mastra_documents`          | Unknown tables                            |
 
 ### Architecture
 

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

@@ -53,7 +53,7 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
 
 **enableServerLogs** (`boolean`): Whether to enable logging for this server. (Default: `true`)
 
-**requireToolApproval** (`boolean | (params: RequireToolApprovalContext) => boolean | Promise<boolean>`): Require human approval before executing tools from this server. When set to \`true\`, all tools require approval. When set to a function, the function is called with the tool name, arguments, and request context to dynamically decide whether approval is needed.
+**requireToolApproval** (`boolean | (params: RequireToolApprovalContext) => boolean | Promise<boolean>`): Require human approval before executing tools from this server. When set to \`true\`, all tools require approval. When set to a function, the function is called with the tool name, arguments, request context, and any tool annotations advertised by the server to dynamically decide whether approval is needed.
 
 ## Tool approval
 
@@ -76,7 +76,7 @@ const mcp = new MCPClient({
 
 ### Dynamic approval with a function
 
-Pass a function to decide per-call whether approval is needed. The function receives the tool name, the arguments the model passed, and any request context from the incoming request:
+Pass a function to decide per-call whether approval is needed. The function receives the tool name, the arguments the model passed, any request context from the incoming request, and the tool's MCP `annotations` (when the server advertises them):
 
 ```typescript
 const mcp = new MCPClient({
@@ -98,6 +98,31 @@ const mcp = new MCPClient({
 
 The function can also be async. It receives `requestContext` from the incoming request, which you can use for auth checks or other per-request logic.
 
+### Use tool annotations from a trusted server
+
+If you trust the MCP server, you can use its [tool annotations](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, `title`) to drive approval decisions:
+
+```typescript
+const mcp = new MCPClient({
+  servers: {
+    github: {
+      url: new URL('http://localhost:3000/mcp'),
+      requireToolApproval: ({ annotations }) => {
+        // Skip approval for tools the server has marked read-only
+        if (annotations?.readOnlyHint) return false
+        // Always require approval for destructive tools
+        if (annotations?.destructiveHint) return true
+        return true
+      },
+    },
+  },
+})
+```
+
+Per the MCP specification, **clients MUST consider tool annotations to be untrusted unless they come from trusted servers**. Annotations are advisory hints, not a security boundary — a malicious or buggy server can claim a tool is read-only when it isn't. Only use annotations to relax approval requirements for servers you trust.
+
+The same annotations are also exposed on the tools returned by `listTools()` and `listToolsets()` under `tool.mcp.annotations`, so you can inspect them when wiring tools into an agent.
+
 ## Methods
 
 ### `listTools()`