@mastra/mcp-docs-server 1.1.46-alpha.3 → 1.1.46-alpha.4

package/.docs/reference/storage/clickhouse.md

@@ -8,7 +8,7 @@ ClickHouse is most commonly used as the dedicated observability backend in a [co
 
 Production observability for traces, logs, metrics, scores, and feedback.
 
-For local development, use a composite store that combines [LibSQL](https://mastra.ai/reference/storage/libsql) (for memory and workflows) and `@mastra/duckdb` (for observability). Neither alone covers a development setup: LibSQL does not implement the observability domain, and DuckDB does not implement the other domains. See the [observability overview](https://mastra.ai/docs/observability/overview) for an example.
+For local development, use a composite store that combines [LibSQL](https://mastra.ai/reference/storage/libsql) (for memory and workflows) and `@mastra/duckdb` (for observability). Neither alone covers a development setup: LibSQL doesn't implement the observability domain, and DuckDB doesn't implement the other domains. See the [observability overview](https://mastra.ai/docs/observability/overview) for an example.
 
 ## Installation
 
@@ -44,7 +44,7 @@ You will also need a running ClickHouse server. See [Hosting options](#hosting-o
 
 `ObservabilityStorageClickhouseVNext` is the current observability domain implementation. It uses an insert-only schema backed by `ReplacingMergeTree` and is optimized for the volume produced by traces, logs, metrics, scores, and feedback.
 
-Compose it with another storage adapter so observability writes do not contend with your application data:
+Compose it with another storage adapter so observability writes don't contend with your application data:
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -85,7 +85,7 @@ export const mastra = new Mastra({
 
 ### Observability with the legacy domain
 
-`ObservabilityStorageClickhouse` is the original observability adapter and remains supported for projects that have not migrated to the vNext schema. The configuration shape is the same as the vNext class.
+`ObservabilityStorageClickhouse` is the original observability adapter and remains supported for projects that haven't migrated to the vNext schema. The configuration shape is the same as the vNext class.
 
 ```typescript
 import { ObservabilityStorageClickhouse } from '@mastra/clickhouse'
@@ -182,10 +182,55 @@ The same `client` form is accepted by `ObservabilityStorageClickhouse` and `Obse
 
 **ttl** (`object`): Per-table TTL configuration applied at table creation time. Accepts row-level and column-level TTLs in interval units from \`NANOSECOND\` through \`YEAR\`.
 
+**replication** (`{ cluster?: string; zookeeperPath?: string; replicaName?: string }`): Opt-in replicated table configuration for multi-replica ClickHouse clusters. When set, Mastra creates replicated MergeTree tables. When \`cluster\` is set, Mastra also adds \`ON CLUSTER\` to Mastra-owned data definition language (DDL).
+
 **disableInit** (`boolean`): When \`true\`, the store does not run table creation or migrations on first use. Call \`storage.init()\` explicitly from your deployment scripts. (Default: `false`)
 
 `ClickhouseStore` also accepts every option from `ClickHouseClientConfigOptions` (such as `database`, `request_timeout`, `compression`, `keep_alive`, and `max_open_connections`).
 
+### Replicated clusters
+
+Use `replication` when Mastra writes to a multi-replica ClickHouse cluster through a load balancer.
+
+```typescript
+const storage = new ClickhouseStoreVNext({
+  id: 'clickhouse-storage',
+  url: process.env.CLICKHOUSE_URL!,
+  username: process.env.CLICKHOUSE_USERNAME!,
+  password: process.env.CLICKHOUSE_PASSWORD!,
+  replication: {
+    cluster: 'company_cluster',
+  },
+})
+```
+
+When `replication` is set, Mastra rewrites its `MergeTree` and `ReplacingMergeTree` table engines to `ReplicatedMergeTree` and `ReplicatedReplacingMergeTree`. The default engine arguments are:
+
+- `zookeeperPath`: `'/clickhouse/tables/{shard}/{database}/{table}'`
+- `replicaName`: `'{replica}'`
+
+The defaults match the most common self-managed convention. If your cluster's existing tables use a different layout (for example `/clickhouse/tables/{shard}/{table}` without the `{database}` segment), set `zookeeperPath` explicitly to match. Mastra does not read your cluster's convention from Keeper, so a mismatched default writes Mastra's metadata to a separate branch from the rest of the cluster.
+
+```typescript
+new ClickhouseStoreVNext({
+  url: process.env.CLICKHOUSE_URL!,
+  username: process.env.CLICKHOUSE_USERNAME!,
+  password: process.env.CLICKHOUSE_PASSWORD!,
+  replication: {
+    cluster: 'company_cluster',
+    zookeeperPath: '/clickhouse/tables/{shard}/{table}',
+  },
+})
+```
+
+Set `cluster` to add `ON CLUSTER` to Mastra-owned DDL such as table creation, materialized view creation, column migrations, TTL changes, and table drops.
+
+Manual maintenance such as `optimizeTable()` and `materializeTtl()` runs on every replica when `cluster` is set. These operations can be expensive on a large cluster. Prefer running them outside peak hours, and let routine merges happen on the background merge queue rather than triggering them on every restart.
+
+If existing Mastra tables use local `MergeTree` or `ReplacingMergeTree` engines, initialization fails while `replication` is enabled. Mastra refuses to silently convert local tables because copy-and-swap is unsafe across replicas. To migrate, recreate the affected tables as `Replicated*` before enabling replication. The typical sequence is: rename the local table, run `CREATE TABLE ... ENGINE = ReplicatedMergeTree(...) ON CLUSTER ...`, run `INSERT INTO ... SELECT * FROM <renamed_local>`, then drop the renamed local table.
+
+Do not set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side, and explicit `ReplicatedMergeTree` engines produce incorrect DDL. `replication` is only for self-managed multi-replica clusters.
+
 ### Observability domain options
 
 `ObservabilityStorageClickhouse` and `ObservabilityStorageClickhouseVNext` accept the same connection options as `ClickhouseStore` (`url`, `username`, `password`, or a pre-configured `client`).
@@ -261,7 +306,7 @@ Two ways to provision the database:
 
 The same approach applies to other hosts with ephemeral filesystems. For application data that should also live off-host, pair this setup with a managed PostgreSQL or LibSQL/Turso instance for the `default` storage.
 
-> **Warning:** Do not point an embedded backend like DuckDB at a path inside an ephemeral container filesystem. Data written there is lost when the container restarts, and on some platforms the path is read-only.
+> **Warning:** Don't point an embedded backend like DuckDB at a path inside an ephemeral container filesystem. Data written there is lost when the container restarts, and on some platforms the path is read-only.
 
 ## Initialization
 

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

@@ -240,6 +240,38 @@ const storage = new MastraCompositeStore({
 })
 ```
 
-> **Note:** `ObservabilityStorageClickhouseVNext` is the current observability domain implementation. The legacy `ObservabilityStorageClickhouse` class is also exported and remains supported for projects that have not migrated. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
+> **Note:** `ObservabilityStorageClickhouseVNext` is the current observability domain implementation. The legacy `ObservabilityStorageClickhouse` class is also exported and remains supported for projects that haven't migrated. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
+
+### Replicated ClickHouse for multi-replica clusters
+
+For self-managed ClickHouse clusters with multiple replicas, set `replication` so Mastra emits `ReplicatedMergeTree` engines and applies `ON CLUSTER` to its DDL:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { MemoryPG, WorkflowsPG, ScoresPG } from '@mastra/pg'
+import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
+
+const storage = new MastraCompositeStore({
+  id: 'composite',
+  domains: {
+    memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+    workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+    scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+    observability: new ObservabilityStorageClickhouseVNext({
+      url: process.env.CLICKHOUSE_URL,
+      username: process.env.CLICKHOUSE_USERNAME,
+      password: process.env.CLICKHOUSE_PASSWORD,
+      replication: {
+        cluster: 'production_cluster',
+        // Optional (defaults shown):
+        // zookeeperPath: '/clickhouse/tables/{shard}/{database}/{table}',
+        // replicaName: '{replica}',
+      },
+    }),
+  },
+})
+```
+
+Do not set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for the full config shape and operator notes.
 
 > **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [MastraStorageExporter documentation](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) for the full list of supported providers.

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

@@ -176,13 +176,13 @@ For very large cache namespaces, clear incrementally or use narrower prefixes to
 
 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`.
+`clear()` only removes rows whose stored `keyPrefix` exactly matches the configured `keyPrefix`. It doesn't 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.
+`ConvexServerCache` doesn't replace a distributed pub/sub transport. If your app needs live cross-process event delivery, configure a production pub/sub backend separately.
 
 ## Additional notes
 

package/.docs/reference/storage/dsql.md

@@ -2,7 +2,7 @@
 
 The Aurora DSQL storage implementation provides storage using Amazon Aurora DSQL with IAM authentication.
 
-Aurora DSQL does not support PostgreSQL extensions (`CREATE EXTENSION`), including `pgvector`. For vector storage, use a separate vector store such as `@mastra/s3vectors`.
+Aurora DSQL doesn't support PostgreSQL extensions (`CREATE EXTENSION`), including `pgvector`. For vector storage, use a separate vector store such as `@mastra/s3vectors`.
 
 ## Installation
 
@@ -170,7 +170,7 @@ const memoryStore = await storage.getStore('memory')
 const thread = await memoryStore?.getThreadById({ threadId: '...' })
 ```
 
-> **Warning:** If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+> **Warning:** If `init()` isn't called, tables won't be created and storage operations will fail silently or throw errors.
 
 ### Direct Database and Pool Access
 
@@ -193,7 +193,7 @@ This approach is intended for advanced scenarios where low-level access is requi
 
 #### IAM-only authentication
 
-Connections are authenticated with IAM. There are no database passwords. `@mastra/dsql` uses `@aws/aurora-dsql-node-postgres-connector` to generate short-lived auth tokens. You can provide a custom credentials provider via `customCredentialsProvider`.
+Connections are authenticated with IAM. No database passwords are required. `@mastra/dsql` uses `@aws/aurora-dsql-node-postgres-connector` to generate short-lived auth tokens. You can provide a custom credentials provider via `customCredentialsProvider`.
 
 #### Single database, schema-based isolation
 
@@ -201,7 +201,7 @@ Each cluster exposes a single database named `postgres`. Logical separation is d
 
 #### No PostgreSQL extensions
 
-`CREATE EXTENSION` is not supported. This includes `pgvector`, `PostGIS`, and others. For vector storage, use a separate store such as `@mastra/s3vectors` alongside `DSQLStore`.
+`CREATE EXTENSION` isn't supported. This includes `pgvector`, `PostGIS`, and others. For vector storage, use a separate store such as `@mastra/s3vectors` alongside `DSQLStore`.
 
 #### JSON stored as text
 
@@ -209,7 +209,7 @@ JSON/JSONB are available as query types but not as column types. `@mastra/dsql`
 
 #### Schema and DDL constraints
 
-Some PostgreSQL features are not available:
+Some PostgreSQL features aren't available:
 
 - Foreign key constraints
 - `TRUNCATE`
@@ -219,7 +219,7 @@ Indexes are created asynchronously using `CREATE INDEX ASYNC`. The store's `init
 
 #### Transactions and optimistic concurrency
 
-Aurora DSQL uses optimistic concurrency control (OCC) and may return retriable OCC errors under contention. There are limits on transaction duration and size. Large bulk operations should be split into smaller batches at the application level.
+Aurora DSQL uses optimistic concurrency control (OCC) and may return retriable OCC errors under contention. Limits exist on transaction duration and size. Large bulk operations should be split into smaller batches at the application level.
 
 #### Connection lifetime
 
@@ -332,7 +332,7 @@ await storage.createIndex({
 })
 ```
 
-Aurora DSQL does not allow `ASC`/`DESC` in `CREATE INDEX ASYNC`. If you include them, they will be automatically stripped.
+Aurora DSQL doesn't allow `ASC`/`DESC` in `CREATE INDEX ASYNC`. If you include them, they will be automatically stripped.
 
 ### Index Options
 

package/.docs/reference/storage/duckdb.md

@@ -6,11 +6,11 @@ For vector search, see the [DuckDB vector store reference](https://mastra.ai/ref
 
 ## When to use DuckDB
 
-Local development of observability features. DuckDB is embedded and file-based, so it does not require a server and starts instantly. It supports the same observability signals as ClickHouse, which makes it useful for testing dashboards and trace exploration before deploying to a production backend.
+Local development of observability features. DuckDB is embedded and file-based, so it doesn't require a server and starts instantly. It supports the same observability signals as ClickHouse, which makes it useful for testing dashboards and trace exploration before deploying to a production backend.
 
 DuckDB currently implements only the `observability` domain. Pair it with another storage adapter (such as [LibSQL](https://mastra.ai/reference/storage/libsql)) for `memory` and `workflows` in a [composite storage](https://mastra.ai/reference/storage/composite) setup.
 
-> **Warning:** DuckDB is for development and not recommended for production. It runs in-process, persists to a single local file, and does not work on platforms with ephemeral filesystems (such as Railway, Fly.io, Render, Heroku, or serverless containers). For production observability, use [ClickHouse](https://mastra.ai/reference/storage/clickhouse).
+> **Warning:** DuckDB is for development and not recommended for production. It runs in-process, persists to a single local file, and doesn't work on platforms with ephemeral filesystems (such as Railway, Fly.io, Render, Heroku, or serverless containers). For production observability, use [ClickHouse](https://mastra.ai/reference/storage/clickhouse).
 
 ## Installation
 
@@ -110,7 +110,7 @@ const duckdb = new DuckDBStore({ path: ':memory:' })
 
 ### Lower-level types
 
-`@mastra/duckdb` also exports `DuckDBConnection` for sharing a single underlying database across multiple Mastra storage instances, and the corresponding `DuckDBStorageConfig` type. Most applications will not need these directly.
+`@mastra/duckdb` also exports `DuckDBConnection` for sharing a single underlying database across multiple Mastra storage instances, and the corresponding `DuckDBStorageConfig` type. Most applications won't need these directly.
 
 ## Supported domains
 

package/.docs/reference/storage/redis.md

@@ -1,6 +1,6 @@
 # Redis Storage
 
-The Redis storage implementation provides a high-performance storage solution using direct Redis connections via [node-redis](https://github.com/redis/node-redis) (the official Redis client for Node.js). It supports standalone Redis, and through custom client configuration, Redis Sentinel and Cluster deployments.
+The Redis storage implementation provides a high-performance storage solution using direct Redis connections via [`node-redis`](https://github.com/redis/node-redis) (the official Redis client for Node.js). It supports standalone Redis, and through custom client configuration, Redis Sentinel and Cluster deployments.
 
 ## Installation
 
@@ -41,7 +41,7 @@ await storage.init()
 
 ### Using Pre-configured Client
 
-For advanced configurations like Sentinel or Cluster, you can pass a pre-configured redis client:
+For advanced configurations like Sentinel or Cluster, you can pass a pre-configured Redis client:
 
 ```typescript
 import { RedisStore } from '@mastra/redis'
@@ -142,7 +142,7 @@ const storage = new RedisStore({
 
 ### Accessing the Underlying Client
 
-You can access the underlying redis client for custom operations:
+You can access the underlying Redis client for custom operations:
 
 ```typescript
 const storage = new RedisStore({

package/.docs/reference/storage/spanner.md

@@ -138,7 +138,7 @@ Two tables also carry Spanner-specific `STORED` generated columns that the adapt
 
 Both are added via `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` during `init()` and skipped under `initMode: 'validate'` (where the schema is owned externally). When the column is absent, the adapter falls back to a `JSON_VALUE` filter at runtime.
 
-The adapter does not create or use named schemas; use a dedicated database for isolation.
+The adapter doesn't create or use named schemas; use a dedicated database for isolation.
 
 ### Initialization
 
@@ -160,7 +160,7 @@ const mastra = new Mastra({
 })
 ```
 
-If you use storage directly, call `init()` once before the first operation. Spanner does not allow concurrent schema changes, so `SpannerStore.init()` runs each domain's setup sequentially.
+If you use storage directly, call `init()` once before the first operation. Spanner doesn't allow concurrent schema changes, so `SpannerStore.init()` runs each domain's setup sequentially.
 
 ```typescript
 const storage = new SpannerStore({
@@ -175,18 +175,18 @@ const memory = await storage.getStore('memory')
 const thread = await memory?.getThreadById({ threadId: '...' })
 ```
 
-> **Warning:** If `init()` is not called and `disableInit` is true, the required tables will not exist and storage operations will fail.
+> **Warning:** If `init()` isn't called and `disableInit` is true, the required tables won't exist and storage operations will fail.
 
 ### GoogleSQL specifics
 
 A few behaviors differ from other relational adapters:
 
-- Upserts use `INSERT OR UPDATE`. Spanner does not provide a `RETURNING` clause for upserts, so callers needing the post-write state must read it back.
-- There is no `TRUNCATE`; `dangerouslyClearAll()` issues `DELETE WHERE TRUE`.
+- Upserts use `INSERT OR UPDATE`. Spanner doesn't provide a `RETURNING` clause for upserts, so callers needing the post-write state must read it back.
+- No `TRUNCATE` exists; `dangerouslyClearAll()` issues `DELETE WHERE TRUE`.
 - Identifiers are quoted with backticks.
 - DDL is applied through `database.updateSchema(...)`, which is asynchronous (long-running operation).
-- `NULLS FIRST/LAST` is not supported. Ordering with NULL handling is emulated through an `IS NULL` ordering key.
-- JSON containment is not supported natively. `listTraces` `metadata` and `scope` filters compile to per-key `JSON_VALUE(...) = @v` equality checks, and `tags` filters compile to `EXISTS` over `JSON_QUERY_ARRAY(...)`. This differs from Postgres' `@>` containment operator (which can match nested structure in a single index scan) — most one-shot lookups still work but deeply nested structural matches are not expressible.
+- `NULLS FIRST/LAST` isn't supported. Ordering with NULL handling is emulated through an `IS NULL` ordering key.
+- JSON containment isn't supported natively. `listTraces` `metadata` and `scope` filters compile to per-key `JSON_VALUE(...) = @v` equality checks, and `tags` filters compile to `EXISTS` over `JSON_QUERY_ARRAY(...)`. This differs from Postgres' `@>` containment operator (which can match nested structure in a single index scan) — most one-shot lookups still work but deeply nested structural matches aren't expressible.
 
 ### Direct database access
 

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

@@ -168,6 +168,8 @@ const stream = await agent.stream('message for agent')
 
 **options.clientTools** (`ToolsInput`): Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.
 
+**options.hooks** (`ToolHooks`): Per-execution hooks that run before and after tool calls. Overrides matching agent-level hooks for this execution. \`beforeToolCall\` can return \`{ proceed: false, output }\` to skip the tool call.
+
 **options.savePerStep** (`boolean`): Save messages incrementally after each stream step completes (default: false).
 
 **options.requireToolApproval** (`boolean`): When true, all tool calls require explicit approval before execution. The stream will emit \`tool-call-approval\` chunks and pause until \`approveToolCall()\` or \`declineToolCall()\` is called.

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

@@ -82,6 +82,8 @@ await agent.streamLegacy('message for agent')
 
 **options.clientTools** (`ToolsInput`): Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.
 
+**options.hooks** (`ToolHooks`): Per-execution hooks that run before and after tool calls. Overrides matching agent-level hooks for this execution. \`beforeToolCall\` can return \`{ proceed: false, output }\` to skip the tool call.
+
 **options.savePerStep** (`boolean`): Save messages incrementally after each stream step completes (default: false).
 
 **options.providerOptions** (`Record<string, Record<string, JSONValue>>`): Additional provider-specific options that are passed through to the underlying LLM provider. The structure is \`{ providerName: { optionKey: value } }\`. For example: \`{ openai: { reasoningEffort: 'high' }, anthropic: { maxTokens: 1000 } }\`.

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

@@ -62,7 +62,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 just-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`) 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/tools/brightdata.md

@@ -155,9 +155,9 @@ const agent = new Agent({
 
 ## Environment variables
 
-| Variable               | Description                                                                                        |
-| ---------------------- | -------------------------------------------------------------------------------------------------- |
-| `BRIGHTDATA_API_TOKEN` | Your Bright Data API token. Used as the default when `apiKey` is not passed to a factory function. |
+| Variable               | Description                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------- |
+| `BRIGHTDATA_API_TOKEN` | Your Bright Data API token. Used as the default when `apiKey` isn't passed to a factory function. |
 
 ## Related
 

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

@@ -0,0 +1,124 @@
+# createCodeMode()
+
+**Added in:** `@mastra/core@1.38.0`
+
+The `createCodeMode()` function returns a tool and generated instructions that let an agent run multi-tool computations as one TypeScript function. The generated code runs in a workspace sandbox, and each `external_*` call runs the real tool on the host with validation, request context, and tracing.
+
+For a conceptual overview, see [Code mode](https://mastra.ai/docs/agents/code-mode).
+
+## Usage example
+
+Create a code mode tool, add its generated instructions to the agent, and register the returned tool with the same id.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createCodeMode, createTool } from '@mastra/core/tools'
+import { LocalSandbox } from '@mastra/core/workspace'
+import { z } from 'zod'
+
+const getTopProducts = createTool({
+  id: 'getTopProducts',
+  description: 'Get top selling products',
+  inputSchema: z.object({ limit: z.number() }),
+  outputSchema: z.object({
+    products: z.array(z.object({ id: z.string(), name: z.string(), totalSales: z.number() })),
+  }),
+  execute: async ({ limit }) => fetchTopProducts(limit),
+})
+
+const getProductRatings = createTool({
+  id: 'getProductRatings',
+  description: 'Get ratings for a product',
+  inputSchema: z.object({ productId: z.string() }),
+  outputSchema: z.object({ ratings: z.array(z.object({ score: z.number() })) }),
+  execute: async ({ productId }) => fetchRatings(productId),
+})
+
+const { tool, instructions } = createCodeMode({
+  tools: { getTopProducts, getProductRatings },
+  sandbox: new LocalSandbox(),
+})
+
+export const shopAgent = new Agent({
+  name: 'shop-assistant',
+  instructions: ['You are a helpful shopping assistant.', instructions],
+  model: 'openai/gpt-5.5',
+  tools: { execute_typescript: tool },
+})
+```
+
+## Parameters
+
+**config** (`CodeModeConfig`): Configuration for the code mode tool and generated instructions.
+
+**config.tools** (`ToolsInput`): Tools exposed to the generated code as \`external\_\<id>\` functions. Only these tools can be called.
+
+**config.sandbox** (`WorkspaceSandbox`): Sandbox used to execute the generated code. Required unless the agent runs in a workspace that provides a sandbox. Pass \`new LocalSandbox()\` to run on the host explicitly.
+
+**config.timeout** (`number`): Execution timeout in milliseconds.
+
+**config.id** (`string`): The generated tool id.
+
+**transport** (`CodeModeTransport`): Optional transport implementation used to run the generated code in the sandbox. The default transport uses stdio JSON-RPC over the workspace sandbox process API.
+
+## Returns
+
+Returns a `CodeModeResult` object.
+
+**tool** (`Tool<any, any>`): The generated code mode tool. By default, its id is \`execute\_typescript\`.
+
+**instructions** (`string`): Generated model instructions with typed \`external\_\*\` declarations for the configured tools.
+
+## CodeModeToolResult
+
+The generated tool returns a `CodeModeToolResult`.
+
+**success** (`boolean`): Whether the generated code ran to completion without throwing.
+
+**result** (`unknown`): The value returned by the generated code.
+
+**logs** (`string[]`): Captured console output from \`console.log\`, \`console.info\`, \`console.warn\`, and \`console.error\`, in order.
+
+**error** (`{ message: string; name?: string; line?: number }`): Error details when the generated code throws or fails to execute.
+
+**error.message** (`string`): Error message.
+
+**error.name** (`string`): Error name, when available.
+
+**error.line** (`number`): Line number associated with the failure, when available.
+
+## Inspecting instructions
+
+Use `createCodeModeInstructions()` to inspect the exact prompt content generated for a set of tools.
+
+```typescript
+import { createCodeModeInstructions } from '@mastra/core/tools'
+
+console.log(
+  createCodeModeInstructions({
+    tools: { getTopProducts, getProductRatings },
+  }),
+)
+```
+
+The instructions include the usage contract and one typed `declare function external_<id>(...)` line for each configured tool. Tool ids are sanitized into valid TypeScript function names, and conflicting sanitized names throw an error.
+
+## createCodeModeTool()
+
+Use `createCodeModeTool()` when you only need the tool and want to manage instructions separately. Most agents should use `createCodeMode()` so the tool and matching instructions stay together.
+
+```typescript
+import { createCodeModeTool } from '@mastra/core/tools'
+import { LocalSandbox } from '@mastra/core/workspace'
+
+export const codeModeTool = createCodeModeTool({
+  tools: { getTopProducts, getProductRatings },
+  sandbox: new LocalSandbox(),
+})
+```
+
+## Related
+
+- [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)

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

@@ -125,7 +125,7 @@ export const weatherTool = createTool({
 })
 ```
 
-Mastra forwards `strict: true` to model adapters that support strict tool calling. On adapters that do not support strict tool calling, Mastra ignores this option.
+Mastra forwards `strict: true` to model adapters that support strict tool calling. On adapters that don't support strict tool calling, Mastra ignores this option.
 
 ## Example with `toModelOutput`
 

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

@@ -153,7 +153,7 @@ const agent = new Agent({
 })
 ```
 
-When `forwardInstructions` is omitted (the default), instructions are still cached and can be inspected via [`getServerInstructions()`](#getserverinstructions), but are not added to any agent's system prompt.
+When `forwardInstructions` is omitted (the default), instructions are still cached and can be inspected via [`getServerInstructions()`](#getserverinstructions), but aren't added to any agent's system prompt.
 
 > **Security note:** server instructions are forwarded verbatim (subject only to length truncation) into the agent's system prompt. A malicious or compromised MCP server can use them to inject instructions the agent will treat as trusted system guidance. Only enable `forwardInstructions` for servers you trust, and prefer reviewing instructions with `getServerInstructions()` before forwarding instructions from third-party servers.
 
@@ -179,7 +179,7 @@ const res = await agent.stream(prompt, {
 
 ### `getServerInstructions()`
 
-Returns the instructions currently known for each configured MCP server. Servers that have not connected yet, or do not advertise instructions, return `undefined`.
+Returns the instructions currently known for each configured MCP server. Servers that haven't connected yet, or don't advertise instructions, return `undefined`.
 
 ```typescript
 getServerInstructions(): Record<string, string | undefined>
@@ -1065,9 +1065,9 @@ await agent.generate('Hello!', {
 
 ## Handling auth failures inside custom fetch
 
-A custom `fetch` should not `throw` when authentication is unavailable. The Streamable HTTP transport in the MCP SDK opens a long-lived `GET /mcp` "standalone listener" stream in the background to receive server-pushed notifications. Errors on that stream are retried with exponential backoff, and a thrown `fetch` or a cleanly-closed stream can produce an indefinite reconnect loop at roughly one attempt per second.
+A custom `fetch` shouldn't `throw` when authentication is unavailable. The Streamable HTTP transport in the MCP SDK opens a long-lived `GET /mcp` "standalone listener" stream in the background to receive server-pushed notifications. Errors on that stream are retried with exponential backoff, and a thrown `fetch` or a cleanly-closed stream can produce an indefinite reconnect loop at roughly one attempt per second.
 
-Return a synthetic `Response` instead. The [MCP Streamable HTTP specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports) defines `405 Method Not Allowed` as the signal a server returns when it does not offer the GET SSE stream, and the SDK honors it as a terminal status that stops the listener cleanly. Use this to disable the listener when your server does not push notifications.
+Return a synthetic `Response` instead. The [MCP Streamable HTTP specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports) defines `405 Method Not Allowed` as the signal a server returns when it doesn't offer the GET SSE stream, and the SDK honors it as a terminal status that stops the listener cleanly. Use this to disable the listener when your server doesn't push notifications.
 
 The following pattern waits for an auth token on POST requests, attaches it to outgoing headers, and short-circuits the GET listener with a synthetic 405:
 
@@ -1108,7 +1108,7 @@ const mcpClient = new MCPClient({
 })
 ```
 
-Return `405` for the GET listener only when your server does not push notifications back to the client. If your server uses the standalone GET stream, attach the auth token on `GET` requests as well and let the request through.
+Return `405` for the GET listener only when your server doesn't push notifications back to the client. If your server uses the standalone GET stream, attach the auth token on `GET` requests as well and let the request through.
 
 ## Using SSE request headers
 

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

@@ -69,6 +69,8 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
 
 **mapAuthInfoToUser** (`({ authInfo, extra, requestContext }) => unknown | null | undefined | Promise<unknown | null | undefined>`): Maps MCP transport auth data from \`extra.authInfo\` into the \`user\` value used by Mastra FGA checks. Use this when an OAuth-protected MCP server is registered on a Mastra instance with an FGA provider.
 
+**fga** (`{ resourceMapping?: Partial<Record<'tool' | 'tools', { fgaResourceType: string; deriveId?: ({ user, resourceId, requestContext }) => string | undefined }>>; permissionMapping?: Record<string, string> }`): Overrides resource and permission mappings for this MCP server's \`tools/list\` and \`tools/call\` FGA checks. Use this when MCP authorization should be scoped differently from internal agent or workflow tool execution.
+
 **repository** (`Repository`): Optional repository information for the server's source code.
 
 **releaseDate** (`string`): Optional release date of this server version (ISO 8601 string). Defaults to the time of instantiation if not provided.
@@ -1129,6 +1131,49 @@ const server = new MCPServer({
 })
 ```
 
+### Scope MCP tool FGA separately
+
+Use `fga.resourceMapping` and `fga.permissionMapping` when MCP clients need a different authorization scope than internal agent or workflow tool execution. The override applies only to `tools/list` and `tools/call` checks for this MCP server.
+
+```typescript
+import { MastraFGAPermissions } from '@mastra/core/auth/ee'
+
+const server = new MCPServer({
+  id: 'my-server',
+  name: 'My Server',
+  version: '1.0.0',
+  tools: { getUserData },
+  mapAuthInfoToUser: ({ authInfo }) => {
+    const user = authInfo as {
+      extra?: {
+        userId?: string
+        organizationMembershipId?: string
+      }
+    }
+
+    if (!user.extra?.userId) {
+      return null
+    }
+
+    return {
+      id: user.extra.userId,
+      organizationMembershipId: user.extra.organizationMembershipId,
+    }
+  },
+  fga: {
+    resourceMapping: {
+      tool: {
+        fgaResourceType: 'user',
+        deriveId: ({ user }) => (user as { id: string }).id,
+      },
+    },
+    permissionMapping: {
+      [MastraFGAPermissions.TOOLS_EXECUTE]: 'read',
+    },
+  },
+})
+```
+
 ### Setting Up Authentication Middleware
 
 To pass data to your tools, populate `req.auth` on the Node.js request object in your HTTP server middleware before calling `server.startHTTP()`.

package/.docs/reference/tools/perplexity.md

@@ -139,10 +139,10 @@ const agent = new Agent({
 
 ## Environment variables
 
-| Variable             | Description                                                                                     |
-| -------------------- | ----------------------------------------------------------------------------------------------- |
-| `PERPLEXITY_API_KEY` | Your Perplexity API key. Used as the default when `apiKey` is not passed to a factory function. |
-| `PPLX_API_KEY`       | Fallback used when `PERPLEXITY_API_KEY` is unset.                                               |
+| Variable             | Description                                                                                    |
+| -------------------- | ---------------------------------------------------------------------------------------------- |
+| `PERPLEXITY_API_KEY` | Your Perplexity API key. Used as the default when `apiKey` isn't passed to a factory function. |
+| `PPLX_API_KEY`       | Fallback used when `PERPLEXITY_API_KEY` is unset.                                              |
 
 ## Related
 

package/.docs/reference/tools/tavily.md

@@ -295,9 +295,9 @@ const agent = new Agent({
 
 ## Environment variables
 
-| Variable         | Description                                                                                 |
-| ---------------- | ------------------------------------------------------------------------------------------- |
-| `TAVILY_API_KEY` | Your Tavily API key. Used as the default when `apiKey` is not passed to a factory function. |
+| Variable         | Description                                                                                |
+| ---------------- | ------------------------------------------------------------------------------------------ |
+| `TAVILY_API_KEY` | Your Tavily API key. Used as the default when `apiKey` isn't passed to a factory function. |
 
 ## Related
 

package/.docs/reference/voice/aws-nova-sonic.md

@@ -150,7 +150,7 @@ Returns: `Promise<void>`
 
 ### `endAudioInput()`
 
-Signals the end of the current audio turn so the model can finalize its response. Call this when the user stops speaking and the provider is not configured for server-side turn detection.
+Signals the end of the current audio turn so the model can finalize its response. Call this when the user stops speaking and the provider isn't configured for server-side turn detection.
 
 Returns: `Promise<void>`