@mastra/mcp-docs-server 1.2.16 → 1.2.17-alpha.11

package/.docs/reference/browser/browser-viewer.md

@@ -229,4 +229,4 @@ browse skills install
 
 - [BrowserViewer guide](https://mastra.ai/integrations/browsers/browser-viewer): Setup and usage walkthrough
 - [MastraBrowser](https://mastra.ai/reference/browser/mastra-browser): Base class API reference
-- [Workspace overview](https://mastra.ai/docs/workspace/overview): Workspace configuration
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox): Workspace configuration

package/.docs/reference/configuration.md

@@ -483,7 +483,7 @@ export const mastra = new Mastra({
 
 A Mastra workspace gives agents a persistent environment for storing files and executing commands. Agents inherit the global workspace on the `Mastra` class unless they have their own workspace configured.
 
-See the [Workspace documentation](https://mastra.ai/docs/workspace/overview) for implementation details.
+See the [Workspace documentation](https://mastra.ai/docs/workspace/sandbox) for implementation details.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/core/removeWorkspace.md

@@ -24,5 +24,5 @@ When `destroy` is `true` and `workspace.destroy()` throws, the call rejects with
 
 ## Related
 
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
 - [Workspace class](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/reference/datasets/addItem.md

@@ -18,6 +18,7 @@ const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 const item = await dataset.addItem({
   input: { question: 'What is TypeScript?' },
   groundTruth: { answer: 'A typed superset of JavaScript' },
+  scorerIds: ['accuracy', 'relevancy'],
   metadata: { source: 'manual' },
 })
 
@@ -30,6 +31,8 @@ console.log(item.id)
 
 **groundTruth** (`unknown`): Expected output or ground truth for scoring.
 
+**scorerIds** (`string[]`): Scorer IDs that override dataset-attached scorers for this item. An empty array runs no scorers for the item. Omit this field to inherit the dataset scorer IDs.
+
 **metadata** (`Record<string, unknown>`): Arbitrary metadata for the item.
 
 ## Returns
@@ -46,6 +49,8 @@ console.log(item.id)
 
 **result.groundTruth** (`unknown`): Ground truth data.
 
+**result.scorerIds** (`string[]`): Scorer IDs selected for this item. An empty array is an explicit override that runs no scorers.
+
 **result.metadata** (`Record<string, unknown>`): Item metadata.
 
 **result.createdAt** (`Date`): When the item was created.

package/.docs/reference/datasets/addItems.md

@@ -17,8 +17,16 @@ const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 
 const items = await dataset.addItems({
   items: [
-    { input: { question: 'What is AI?' }, groundTruth: { answer: 'Artificial Intelligence' } },
-    { input: { question: 'What is ML?' }, groundTruth: { answer: 'Machine Learning' } },
+    {
+      input: { question: 'What is AI?' },
+      groundTruth: { answer: 'Artificial Intelligence' },
+      scorerIds: ['accuracy'],
+    },
+    {
+      input: { question: 'What is ML?' },
+      groundTruth: { answer: 'Machine Learning' },
+      scorerIds: [],
+    },
     { input: { question: 'What is DL?' }, metadata: { category: 'deep-learning' } },
   ],
 })
@@ -34,6 +42,8 @@ console.log(`Added ${items.length} items`)
 
 **items.groundTruth** (`unknown`): Expected output or ground truth.
 
+**items.scorerIds** (`string[]`): Scorer IDs that override dataset-attached scorers for this item. An empty array runs no scorers for the item.
+
 **items.metadata** (`Record<string, unknown>`): Arbitrary metadata.
 
 ## Returns

package/.docs/reference/datasets/startExperiment.md

@@ -59,7 +59,7 @@ console.log(`Status: ${summary2.status}`)
 
 **targetId** (`string`): ID of the registered target. Use with targetType.
 
-**scorers** (`(MastraScorer | string)[] | AgentScorerConfig | WorkflowScorerConfig`): Scorers to evaluate each result. Accepts a flat array of MastraScorer instances or registered scorer IDs, or the same categorised config shape used by runEvals (AgentScorerConfig / WorkflowScorerConfig). Trajectory scorers (type: "trajectory") automatically receive a pre-extracted Trajectory as their output regardless of which form is used. For workflow targets, per-step scorers can be passed via scorers: { steps: { stepId: \[...] } } and run against each step's output; their results carry the originating stepId and keep targetScope: "span" (matching runEvals).
+**scorers** (`(MastraScorer | string)[] | AgentScorerConfig | WorkflowScorerConfig`): Scorers to evaluate each result. Accepts a flat array of MastraScorer instances or registered scorer IDs, or the same categorised config shape used by runEvals (AgentScorerConfig / WorkflowScorerConfig). When this option is provided, including as \[] or an empty categorized config, it overrides item-level and dataset-level scorer IDs for every item. When omitted, each item uses its own scorerIds when present, then falls back to the dataset scorer IDs. Sources aren't merged. Trajectory scorers (type: "trajectory") automatically receive a pre-extracted Trajectory as their output regardless of which form is used. Workflow step scorers are supported only through this run-level categorized configuration. Their results carry the originating stepId and keep targetScope: "span" (matching runEvals).
 
 **name** (`string`): Display name for the experiment.
 

package/.docs/reference/datasets/updateItem.md

@@ -19,6 +19,7 @@ const updated = await dataset.updateItem({
   itemId: 'item-id',
   input: { question: 'What is TypeScript?' },
   groundTruth: { answer: 'A typed superset of JavaScript' },
+  scorerIds: null,
   metadata: { reviewed: true },
 })
 ```
@@ -31,6 +32,8 @@ const updated = await dataset.updateItem({
 
 **groundTruth** (`unknown`): Updated ground truth.
 
+**scorerIds** (`string[] | null`): Scorer IDs that override dataset-attached scorers for this item. Use \[] to run no scorers, null to remove the override and restore dataset inheritance, or omit the field to preserve the current value.
+
 **metadata** (`Record<string, unknown>`): Updated metadata.
 
 ## Returns

package/.docs/reference/file-based-agents/workspace.md

@@ -4,9 +4,9 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-A [workspace](https://mastra.ai/docs/workspace/overview) gives an agent filesystem access and command execution. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`, so they can read and write files and run shell commands without extra configuration.
+A [workspace](https://mastra.ai/docs/workspace/sandbox) assembles capabilities such as filesystem access and command execution. The configured backends determine which tools are available. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`. This default includes filesystem access and command execution, so agents can read and write files and run shell commands without extra configuration.
 
-Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Workspaces](https://mastra.ai/docs/workspace/overview).
+Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Sandbox](https://mastra.ai/docs/workspace/sandbox).
 
 ## Default workspace
 
@@ -65,7 +65,7 @@ Customize the workspace when the default local directory isn't enough. Common re
 - Add workspace search with BM25 or vector search.
 - Share one workspace across multiple agents.
 
-For provider patterns and runtime behavior, see the [workspace overview](https://mastra.ai/docs/workspace/overview), [sandbox guide](https://mastra.ai/docs/workspace/sandbox), and [workspace search](https://mastra.ai/docs/workspace/search).
+For provider patterns and runtime behavior, see the [sandbox guide](https://mastra.ai/docs/workspace/sandbox) and [workspace search](https://mastra.ai/docs/workspace/search).
 
 ## Runtime boundary
 

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

@@ -57,6 +57,8 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.instruction** (`string`): Custom instruction appended to the Observer's system prompt. Use this to customize what the Observer focuses on, such as domain-specific preferences or priorities.
 
+**observation.continuationHints** (`boolean | { currentTask?: boolean; suggestedResponse?: boolean }`): Which continuation-hint sections the Observer emits. Pass false to disable both, or an object to disable them individually. Agents that drive their own control flow generally want { suggestedResponse: false } so memory does not compete for what the agent says next. A previously stored hint stops being injected into context once both observation and reflection disable its section.
+
 **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.extract** (`Extractor[]`): Custom values to extract after observation. Schema-less extractors are requested inline in the Observer output. Schema-backed extractors run as a follow-up structured output call and are stored in thread OM metadata.
@@ -97,6 +99,8 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **reflection.instruction** (`string`): Custom instruction appended to the Reflector's system prompt. Use this to customize how the Reflector consolidates observations, such as prioritizing certain types of information.
 
+**reflection.continuationHints** (`boolean | { currentTask?: boolean; suggestedResponse?: boolean }`): Which continuation-hint sections the Reflector emits. Pass false to disable both, or an object to disable them individually. A previously stored hint stops being injected into context once both observation and reflection disable its section.
+
 **reflection.extract** (`Extractor[]`): Custom values to extract after reflection. Schema-less extractors are requested inline in the Reflector output. Schema-backed extractors run as a follow-up structured output call and are stored in thread OM metadata.
 
 **reflection.observationTokens** (`number`): Token count of observations that triggers reflection. When observation tokens exceed this threshold, the Reflector agent is called to condense them.

package/.docs/reference/observability/tracing/exporters/mastra-platform-exporter.md

@@ -189,6 +189,8 @@ When an organization has exhausted its observability quota, the Mastra platform
 
 The probe timer doesn't keep the Node.js process alive, so short-lived and serverless processes exit normally while paused.
 
+Every request the exporter sends (batch uploads for all five signal types, plus the traces recovery probe) includes the `x-mastra-observability-capabilities: quota-pause-v1` header. This tells the platform that the client understands the quota-pause contract, so it can safely respond with `402` instead of silently dropping telemetry for older clients that would retry it.
+
 ### Endpoint routing
 
 - Base origins derive signal endpoints automatically

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

@@ -45,11 +45,12 @@ Mastra agents don't add this processor automatically. Add it explicitly when you
 
 `ProviderHistoryCompat` includes these built-in compatibility rules:
 
-| Rule                                        | Provider  | Timing                      | Behavior                                                                                                                          |
-| ------------------------------------------- | --------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `anthropic-tool-id-format`                  | Anthropic | Reactive API error recovery | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` and retries the request.                                   |
-| `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.       |
+| Rule                                        | Provider     | Timing                      | Behavior                                                                                                                                                    |
+| ------------------------------------------- | ------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `anthropic-tool-id-format`                  | Anthropic    | Reactive API error recovery | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` and retries the request.                                                             |
+| `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.                                 |
+| `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. |
 
 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.
 

package/.docs/reference/processors/skill-search-processor.md

@@ -112,4 +112,4 @@ Reserve workspace file tools such as `mastra_workspace_read_file` for explicit f
 
 - [ToolSearchProcessor](https://mastra.ai/reference/processors/tool-search-processor)
 - [Processors](https://mastra.ai/docs/agents/processors)
-- [Workspace Skills](https://mastra.ai/docs/workspace/overview)
+- [Workspace Skills](https://mastra.ai/docs/workspace/skills)

package/.docs/reference/pubsub/base.md

@@ -79,10 +79,16 @@ Registers a callback to receive events published to a topic. When `options.group
 
 Pass `options.batch` to opt in to batched delivery. The callback signature is unchanged: a batch of N events is delivered as N consecutive `cb(event, ack, nack)` calls in publish order. Batching is honored only when the backend's [`supportsNativeBatching`](#properties) is `true`. Other backends ignore the option and deliver events one at a time.
 
+Set `options.startFrom` to `"latest"` to receive only events published after a new consumer group is created. The default, `"earliest"`, includes retained events. Existing consumer groups keep their current checkpoint.
+
 ```typescript
-await pubsub.subscribe('my-topic', (event, ack, nack) => {
-  console.log(event)
-})
+await pubsub.subscribe(
+  'my-topic',
+  (event, ack, nack) => {
+    console.log(event)
+  },
+  { startFrom: 'latest' },
+)
 ```
 
 #### `unsubscribe(topic, cb)`
@@ -151,6 +157,8 @@ await pubsub.subscribeFromOffset('my-topic', 42, event => {
 
 **supportsNativeBatching** (`boolean`): Whether the implementation honors options.batch on subscribe(). Defaults to false. Backends that integrate batching internally override this and return true.
 
+**supportsOffsets** (`boolean`): Whether subscribeFromOffset() honors numeric offsets. Defaults to false. A non-zero offset on an unsupported implementation falls back to replay subscription and emits a diagnostic warning when a logger is configured.
+
 ## Types
 
 ### `Event`
@@ -175,6 +183,8 @@ await pubsub.subscribeFromOffset('my-topic', 42, event => {
 
 **batch** (`SubscribeBatchOptions`): Opt in to batched delivery for this subscription. When omitted, events are delivered one at a time. Honored only by backends where supportsNativeBatching is true.
 
+**startFrom** (`"earliest" | "latest"`): Starting position used when a backend creates a new consumer group. "earliest" includes retained events. "latest" receives only events published after group creation. Existing groups keep their checkpoint. (Default: `"earliest"`)
+
 ### `SubscribeBatchOptions`
 
 Per-subscription batching policy. The callback signature doesn't change. A batch of N events becomes N consecutive callback invocations in publish order.

package/.docs/reference/pubsub/caching-pubsub.md

@@ -46,6 +46,8 @@ const pubsub = withCaching(new EventEmitterPubSub(), new InMemoryServerCache())
 
 **supportsNativeBatching** (`boolean`): Mirrors the inner pub/sub. Returns true only when the wrapped implementation supports batching.
 
+**supportsOffsets** (`boolean`): Returns true. Cached events have sequential indexes that support numeric offset replay.
+
 ## Methods
 
 `CachingPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. It overrides the replay methods to read cached events. The methods below describe the caching behavior.

package/.docs/reference/pubsub/event-emitter.md

@@ -51,6 +51,8 @@ const pubsub = new EventEmitterPubSub(undefined, { logger })
 
 **supportsNativeBatching** (`boolean`): Returns true. Subscribers can opt in to batched delivery with options.batch.
 
+**supportsOffsets** (`boolean`): Returns false. The in-memory emitter does not retain indexed event history.
+
 ## Methods
 
 `EventEmitterPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. The methods below have behavior specific to this implementation.

package/.docs/reference/pubsub/redis-streams.md

@@ -77,6 +77,8 @@ export const mastra = new Mastra({
 
 **supportedModes** (`ReadonlyArray<"pull" | "push">`): Returns \["pull"].
 
+**supportsOffsets** (`boolean`): Returns false. Redis stream anchors support start positions, but not the numeric indexes used by subscribeFromOffset().
+
 ## Methods
 
 `RedisStreamsPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. The methods below have behavior specific to this implementation.
@@ -85,10 +87,16 @@ export const mastra = new Mastra({
 
 Subscribes to a topic. With `options.group`, members of the group share events through a Redis consumer group. Without a group, the subscriber receives every event through a private consumer group.
 
+Set `options.startFrom` to `"latest"` to skip retained entries when Redis creates the consumer group. The default, `"earliest"`, reads retained entries first. This option doesn't reset an existing group's checkpoint.
+
 ```typescript
-await pubsub.subscribe('workflow.events', (event, ack, nack) => {
-  console.log(event)
-})
+await pubsub.subscribe(
+  'workflow.events',
+  (event, ack, nack) => {
+    console.log(event)
+  },
+  { group: 'live-workers', startFrom: 'latest' },
+)
 ```
 
 ### `flush()`

package/.docs/reference/tools/create-code-mode.md

@@ -126,4 +126,4 @@ export const codeModeTool = createCodeModeTool({
 
 - [Code mode](https://mastra.ai/docs/agents/code-mode)
 - [createTool()](https://mastra.ai/reference/tools/create-tool)
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)

package/.docs/reference/tools/create-tool.md

@@ -89,7 +89,7 @@ The first `execute` parameter is the validated value from `inputSchema`. Destruc
 
 **onInputAvailable** (`function`): Optional callback invoked when the complete tool input is available and parsed. Signature: ({ input, ...options }: { input: TSchemaIn } & ToolCallOptions) => void | PromiseLike\<void>.
 
-**onOutput** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Signature: ({ output, toolName, ...options }: { output: TSchemaOut; toolName: string } & Omit\<ToolCallOptions, 'messages'>) => void | PromiseLike\<void>.
+**onOutput** (`function`): Optional callback invoked after a server-executed tool returns output or after a successful client-executed tool result arrives on a follow-up request. Error results don't invoke the hook. For client-executed results, TSchemaOut is a static type only: the server doesn't validate the result against outputSchema, so treat the output as untrusted. Signature: ({ output, toolName, ...options }: { output: TSchemaOut; toolName: string } & Omit\<ToolCallOptions, 'messages'>) => void | PromiseLike\<void>.
 
 Runtime-populated fields such as `mastra` and `mcpMetadata` appear in source types but are set by Mastra or MCP adapters. You don't need to configure them for ordinary `createTool()` usage.
 
@@ -440,7 +440,7 @@ export const tool = createTool({
 
 #### `onOutput`
 
-Called after the tool has successfully executed and returned output. Useful for logging results, triggering follow-up actions, or analytics.
+Called after a server-executed tool returns output or after a successful client-executed tool result arrives on a follow-up request. Use it to log results or trigger follow-up actions.
 
 ```typescript
 export const tool = createTool({
@@ -459,9 +459,15 @@ export const tool = createTool({
 })
 ```
 
+Client-executed tools don't define an `execute` function. The browser runs the tool and sends the result on a follow-up request. `onOutput` then runs on the server. Only a correlated successful result invokes the hook: error results, such as the AI SDK `error-text` and `error-json` output types, don't invoke `onOutput`.
+
+For client-executed results, the follow-up request must include both the assistant tool call and the tool result, which `@mastra/client-js` sends automatically. A request that carries only the tool result doesn't fire the hook. In this case the callback receives `{ toolCallId, toolName, output, abortSignal }` only.
+
+Delivery is at least once, so a retried request runs the hook again. Keep the hook idempotent and treat client output as untrusted data: the server doesn't validate the result against `outputSchema`, so the `output` type is a static type only.
+
 ### Hook execution order
 
-For a typical streaming tool call, the hooks are invoked in this order:
+For a typical streaming tool call on a server-executed tool, the hooks are invoked in this order:
 
 1. **onInputStart**: Input streaming begins
 2. **onInputDelta**: Called multiple times as chunks arrive
@@ -469,6 +475,8 @@ For a typical streaming tool call, the hooks are invoked in this order:
 4. Tool's **execute** function runs
 5. **onOutput**: Tool has completed successfully
 
+For a client-executed tool, steps 1-3 run while the model streams the tool call, the client runs the tool instead of a server-side `execute`, and `onOutput` runs on the follow-up request that carries a successful result.
+
 ### Hook parameters
 
 Hook callbacks receive these source-backed parameter shapes:

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

@@ -223,17 +223,23 @@ Retrieves all tools from all configured servers, with tool names namespaced by t
 new Agent({ id: 'agent', tools: await mcp.listTools() })
 ```
 
-### `listToolsWithErrors()`
+### `listToolsWithErrors(options?)`
 
 Retrieves all tools from all configured servers, with tool names namespaced by their server name. Also returns per-server errors for servers that failed to connect or list tools.
 
+Set `perServerTimeoutMs` to limit how long discovery waits for each server. Servers that finish within the limit remain in `tools`. Timed-out servers appear in `errors`, and `durations` reports each server's discovery time in milliseconds.
+
 ```typescript
-const { tools, errors } = await mcp.listToolsWithErrors()
+const { tools, errors, durations } = await mcp.listToolsWithErrors({
+  perServerTimeoutMs: 3_000,
+})
 
 new Agent({ id: 'agent', tools })
-console.log(errors)
+console.log(errors, durations)
 ```
 
+When called without options, the method returns only `tools` and `errors`.
+
 ### `listToolsets()`
 
 Returns an object mapping namespaced tool names (in the format `serverName.toolName`) to their tool implementations. Intended to be passed at runtime into the generate or stream method.
@@ -244,6 +250,21 @@ const res = await agent.stream(prompt, {
 })
 ```
 
+### `listToolsetsWithErrors(options?)`
+
+Returns toolsets grouped by server name, along with per-server discovery errors. Set `perServerTimeoutMs` to limit each server independently and include per-server `durations` in milliseconds.
+
+```typescript
+const { toolsets, errors, durations } = await mcp.listToolsetsWithErrors({
+  perServerTimeoutMs: 3_000,
+})
+
+const res = await agent.stream(prompt, { toolsets })
+console.log(errors, durations)
+```
+
+When called without options, the method returns only `toolsets` and `errors`.
+
 ### `listToolDefinitions()`
 
 Returns every server's tools as plain, serializable definitions, grouped by server name and keyed by the server's own tool name (without the `serverName_toolName` namespacing that `listTools()` applies).
@@ -256,18 +277,26 @@ const definitions = await mcp.listToolDefinitions()
 await cache.set('mcp-tools', JSON.stringify(definitions))
 ```
 
-### `listToolDefinitionsWithErrors()`
+### `listToolDefinitionsWithErrors(options?)`
 
 Like `listToolDefinitions()`, but also returns per-server errors for servers that failed to connect. Use this when caching a catalog, so you don't persist a partial manifest that omits a server that was down at discovery time.
 
+Set `perServerTimeoutMs` to limit each server independently. When options are provided, `durations` reports each server's discovery time in milliseconds.
+
 ```typescript
-const { definitions, errors } = await mcp.listToolDefinitionsWithErrors()
+const { definitions, errors, durations } = await mcp.listToolDefinitionsWithErrors({
+  perServerTimeoutMs: 3_000,
+})
 
 if (Object.keys(errors).length === 0) {
   await cache.set('mcp-tools', JSON.stringify(definitions))
 }
+
+console.log(durations)
 ```
 
+When called without options, the method returns only `definitions` and `errors`.
+
 ### `toolFromDefinition()`
 
 Rebuilds a single executable tool from a cached definition. No connection is opened here. The client connects lazily, the first time the tool is executed.

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

@@ -1637,6 +1637,9 @@ const calculatorTool = createTool({
     num2: z.number(),
     operation: z.enum(['add', 'subtract']),
   }),
+  mcp: {
+    _meta: { ui: { resourceUri: 'ui://calculator/main' } },
+  },
   execute: async ({ num1, num2, operation }) => {
     const result = operation === 'add' ? num1 + num2 : num1 - num2
     return {
@@ -1660,7 +1663,7 @@ const server = new MCPServer({
 })
 ```
 
-Link a tool to its app resource by setting `_meta.ui.resourceUri` on the tool to the matching `ui://` URI. The server auto-normalizes this metadata when registering tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/overview) for the full app bridge API and usage patterns.
+Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `createTool()` to the matching `ui://` URI. The server normalizes this metadata for older hosts when listing tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/overview) for the full app bridge API and usage patterns.
 
 ## Related information
 

package/.docs/reference/workspace/local-filesystem.md

@@ -356,4 +356,4 @@ Set `WORKSPACE_PATH` in your environment to an absolute path like `/home/user/my
 
 - [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
 - [Workspace class](https://mastra.ai/reference/workspace/workspace-class)
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)

package/.docs/reference/workspace/local-sandbox.md

@@ -223,4 +223,4 @@ This separation prevents sandboxed processes from reading or modifying their own
 - [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
 - [WorkspaceSandbox Interface](https://mastra.ai/reference/workspace/sandbox)
 - [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
-- [Workspace Overview](https://mastra.ai/docs/workspace/overview)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)

package/.docs/reference/workspace/workspace-class.md

@@ -31,9 +31,9 @@ const workspace = new Workspace({
 
 **name** (`string`): Human-readable name (Default: `workspace-{id}`)
 
-**filesystem** (`WorkspaceFilesystem | WorkspaceFilesystemResolver`): Filesystem provider instance, or a resolver function that receives requestContext and returns a filesystem per request. See dynamic filesystem.
+**filesystem** (`WorkspaceFilesystem | WorkspaceFilesystemResolver`): Filesystem provider instance, or a resolver function that receives requestContext and returns a filesystem per request. See multi-tenant filesystems.
 
-**sandbox** (`WorkspaceSandbox | WorkspaceSandboxResolver`): Sandbox provider instance, or a resolver function that receives requestContext and returns a sandbox per request. See dynamic sandbox.
+**sandbox** (`WorkspaceSandbox | WorkspaceSandboxResolver`): Sandbox provider instance, or a resolver function that receives requestContext and returns a sandbox per request. See multi-tenant sandboxes.
 
 **instructions.dynamicSandbox** (`'placeholder' | 'resolve' | (({ requestContext }) => string)`): Controls how a resolver-backed sandbox contributes to workspace instructions. 'placeholder' (default) emits stable text without calling the resolver. 'resolve' calls the resolver and uses the sandbox's own instructions. A function returns custom text without resolving. Has no effect on a static sandbox. (Default: `'placeholder'`)
 
@@ -57,15 +57,9 @@ const workspace = new Workspace({
 
 **tools** (`WorkspaceToolsConfig`): Per-tool configuration for enabling tools and setting safety options
 
-**tools.enabled** (`boolean`): Whether the tool is available to agents
+**tools.enabled** (`boolean | ((context: ToolConfigContext) => boolean | Promise<boolean>)`): Default availability for all workspace tools. Per-tool settings take precedence.
 
-**tools.requireApproval** (`boolean`): Whether the tool requires user approval before execution
-
-**tools.name** (`string`): Custom name to expose this tool as. Replaces the default mastra\_workspace\_\* name. The config key must still use the original WORKSPACE\_TOOLS constant.
-
-**tools.requireReadBeforeWrite** (`boolean`): For write tools: require reading the file first to prevent overwrites
-
-**tools.maxOutputTokens** (`number`): Maximum tokens for tool output. Output exceeding this limit is truncated using tiktoken.
+**tools.requireApproval** (`boolean | ((context: ToolConfigWithArgsContext) => boolean | Promise<boolean>)`): Default approval policy for all workspace tools. Per-tool settings take precedence.
 
 **tools.writeLockTimeoutMs** (`number`): Maximum time in milliseconds a write tool waits to acquire the per-file write lock before failing. Raise this for slow or cold-starting filesystems (e.g. remote sandboxes).
 
@@ -73,6 +67,17 @@ const workspace = new Workspace({
 
 **operationTimeout** (`number`): Timeout for operations in milliseconds
 
+For a resolver-backed sandbox, the default `'placeholder'` mode avoids provisioning a sandbox while workspace instructions are built. Set `instructions.dynamicSandbox` to `'resolve'` when the instructions must come from the resolved sandbox:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
+  instructions: { dynamicSandbox: 'resolve' },
+})
+```
+
+This calls the resolver while building instructions. To describe a request-specific environment without provisioning it, pass a function that returns instruction text from `requestContext` instead.
+
 ## Tool configuration
 
 The `tools` option accepts a `WorkspaceToolsConfig` object that controls which workspace tools are enabled and their safety settings.
@@ -97,12 +102,44 @@ const workspace = new Workspace({
 })
 ```
 
-The config object has two parts:
+The config object has two types of settings:
+
+- **Global settings**: `enabled` and `requireApproval` apply to all workspace tools unless overridden. `hooks` and `writeLockTimeoutMs` are global-only and can't be configured per tool.
+- **Per-tool overrides**: Use `WORKSPACE_TOOLS` constants as keys to configure individual tools
+
+Per-tool overrides accept the following options:
+
+**enabled** (`boolean | ((context: ToolConfigContext) => boolean | Promise<boolean>)`): Whether the tool is available. Functions are evaluated when Mastra lists tools. (Default: `true`)
+
+**requireApproval** (`boolean | ((context: ToolConfigWithArgsContext) => boolean | Promise<boolean>)`): Whether the tool requires approval. Functions are evaluated when the tool executes. (Default: `false`)
+
+**name** (`string`): Name exposed to the model instead of the default mastra\_workspace\_\* name.
 
-- **Global defaults** (`enabled`, `requireApproval`): Apply to all tools unless overridden
-- **Per-tool overrides** - Use `WORKSPACE_TOOLS` constants as keys to configure individual tools
+**requireReadBeforeWrite** (`boolean | ((context: ToolConfigWithArgsContext) => boolean | Promise<boolean>)`): For write tools, require the agent to read an existing file before changing it. (Default: `false`)
+
+**maxOutputTokens** (`number`): Maximum output tokens for tools that support token-based truncation.
+
+`ToolConfigContext` contains `{ requestContext, workspace }`. Execution-time policies use `ToolConfigWithArgsContext`, which also contains the tool's `args`.
+
+```typescript
+import { Workspace, WORKSPACE_TOOLS } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  id: 'my-workspace',
+  tools: {
+    enabled: ({ requestContext }) => requestContext.get('workspace-tools') === true,
+    [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
+      requireApproval: ({ args }) => (args.path as string).startsWith('/protected'),
+      requireReadBeforeWrite: true,
+    },
+    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
+      maxOutputTokens: 5000,
+    },
+  },
+})
+```
 
-See [workspace overview](https://mastra.ai/docs/workspace/overview) for more examples.
+See [Filesystem tools](https://mastra.ai/docs/workspace/filesystem), [Sandbox tools](https://mastra.ai/docs/workspace/sandbox), [LSP inspection](https://mastra.ai/docs/workspace/lsp), and [Search tools](https://mastra.ai/docs/workspace/search) for capability-specific configuration.
 
 ### Tool name remapping
 
@@ -469,7 +506,7 @@ The `execute_command` tool accepts a `backgroundProcesses` option for lifecycle
 
 **backgroundProcesses.abortSignal** (`AbortSignal | null | false`): Abort signal for background processes. undefined (default) uses the agent's signal. null or false disables abort — processes persist after agent shutdown.
 
-See [Background process callbacks](https://mastra.ai/docs/workspace/sandbox) for usage examples.
+See [Background processes](https://mastra.ai/docs/workspace/sandbox) for callback examples.
 
 ### Search tools
 

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @mastra/mcp-docs-server
 
+## 1.2.17-alpha.10
+
+### Patch Changes
+
+- Updated dependencies [[`0b4f108`](https://github.com/mastra-ai/mastra/commit/0b4f1089aa8d92e67c2a8e99726822c5ee410784), [`88ddc7c`](https://github.com/mastra-ai/mastra/commit/88ddc7ce01d40175f13a3228b789a906779680bd), [`a7dd322`](https://github.com/mastra-ai/mastra/commit/a7dd32247d95afc539f483ca37f4594af0387f59)]:
+  - @mastra/core@1.60.0-alpha.6
+
+## 1.2.17-alpha.8
+
+### Patch Changes
+
+- Updated dependencies [[`74e5bd3`](https://github.com/mastra-ai/mastra/commit/74e5bd315b8b3a1e04cb6cf480bb0f5fc4951dc8)]:
+  - @mastra/core@1.60.0-alpha.5
+
+## 1.2.17-alpha.6
+
+### Patch Changes
+
+- Updated dependencies [[`d7e6745`](https://github.com/mastra-ai/mastra/commit/d7e67456954863c55440ea9c49bc6ceb9949972d), [`9acb50f`](https://github.com/mastra-ai/mastra/commit/9acb50f71cec9c362f06820033f90ae6b1f8282f), [`46e9e3f`](https://github.com/mastra-ai/mastra/commit/46e9e3f73babe1bc70080a596cf2ac0b9da48519), [`3f9a190`](https://github.com/mastra-ai/mastra/commit/3f9a19057c027155867b9317294ee4ca7bd0581a), [`e8808e3`](https://github.com/mastra-ai/mastra/commit/e8808e3d8eb585a2565be53e56a7e0e1477352a4), [`d4be8c1`](https://github.com/mastra-ai/mastra/commit/d4be8c1739d22d621e3f78790e1dd5eb5ecc3589), [`a5d2eb1`](https://github.com/mastra-ai/mastra/commit/a5d2eb10347eade1ae2816d88f466c25186c54a5), [`13d49d8`](https://github.com/mastra-ai/mastra/commit/13d49d82f434f319d4bd9a4234369d8186f8e102), [`e81744c`](https://github.com/mastra-ai/mastra/commit/e81744cd13c46619c142dc521dc0baac47607a84)]:
+  - @mastra/core@1.60.0-alpha.4
+  - @mastra/mcp@1.17.0-alpha.0
+
+## 1.2.17-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`d8308a2`](https://github.com/mastra-ai/mastra/commit/d8308a2be3c07e777393d1017a381dcae3890d30), [`7aad631`](https://github.com/mastra-ai/mastra/commit/7aad631b43bc10db77d5b8c66b200d7a49d18bf2), [`1794a79`](https://github.com/mastra-ai/mastra/commit/1794a79178c418004a7261b1ad9114066f7ef01d)]:
+  - @mastra/core@1.60.0-alpha.3
+
+## 1.2.17-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [[`7e096f0`](https://github.com/mastra-ai/mastra/commit/7e096f02f0dddbf09b85d306458351245ed2f886), [`8f0a332`](https://github.com/mastra-ai/mastra/commit/8f0a3321bf180368d76fe7b36aa1a8f60f00b6de), [`b098de9`](https://github.com/mastra-ai/mastra/commit/b098de9d7cb9f672e0883a5c716465a3a689693d), [`ef6e295`](https://github.com/mastra-ai/mastra/commit/ef6e295b59bc25a5b61b633a89c97bcfce9fb465), [`208e1b3`](https://github.com/mastra-ai/mastra/commit/208e1b39f30f4b386e494394e9d71d96f0f90241), [`c938d34`](https://github.com/mastra-ai/mastra/commit/c938d34739936c8ecbabd67ad6a4a4396f41c4c6), [`1d9a0ea`](https://github.com/mastra-ai/mastra/commit/1d9a0ea4a9901baee6cd56737243bd6d1f631ac0), [`3667679`](https://github.com/mastra-ai/mastra/commit/3667679db057edfb086846d13369fdda4902ad65), [`49696e8`](https://github.com/mastra-ai/mastra/commit/49696e8e42f870674a0a58f5abcd22cc54dd2864), [`512100a`](https://github.com/mastra-ai/mastra/commit/512100a7d8b7e9c920f2590c6b3612f5de0d3cff), [`9ef432b`](https://github.com/mastra-ai/mastra/commit/9ef432b6faa534b57b0d182a610e13dd9a7123ff), [`b9cf308`](https://github.com/mastra-ai/mastra/commit/b9cf30846f97f99ac1906ee8a68f4f2d117b0378)]:
+  - @mastra/core@1.60.0-alpha.2
+
+## 1.2.17-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`15101bb`](https://github.com/mastra-ai/mastra/commit/15101bb53c0d934f31af6b8813b88191e382a5e5), [`c2c3deb`](https://github.com/mastra-ai/mastra/commit/c2c3debcf670c7082d0a5e553aa99818a864698c), [`33374ba`](https://github.com/mastra-ai/mastra/commit/33374ba359e4fb13eaa918ae925fe167a3c55414), [`c5f964d`](https://github.com/mastra-ai/mastra/commit/c5f964d3f77064e978f8066ec506eed77ba5c63c), [`f8f653f`](https://github.com/mastra-ai/mastra/commit/f8f653f10980d01a73706cc3c8689ca5e40ce808)]:
+  - @mastra/core@1.60.0-alpha.1
+
+## 1.2.17-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`587f6ef`](https://github.com/mastra-ai/mastra/commit/587f6efcfc25880b93760a8607d1cd381ec612fe)]:
+  - @mastra/core@1.59.1-alpha.0
+
 ## 1.2.16
 
 ### Patch Changes