@mastra/mcp-docs-server 1.2.15-alpha.9 → 1.2.16-alpha.1

package/.docs/reference/rag/metadata-filters.md

@@ -2,7 +2,7 @@
 
 # Metadata filters
 
-Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into their native format.
+Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into its native query format. For example, PgVector uses PostgreSQL JSONB predicates, while OracleDB stores metadata as Oracle JSON and compiles filters to `JSON_VALUE`, `JSON_EXISTS`, `REGEXP_LIKE`, and `LIKE` predicates with bound values.
 
 ## Basic example
 
@@ -34,11 +34,11 @@ const results = await store.query({
 
 ### Array Operators
 
-`$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB
+`$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB, OracleDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB, OracleDB
 
 ### Logical Operators
 
-`$and`Logical AND{ $and: \[{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }Supported by: All except Vectorize, Couchbase`$or`Logical OR{ $or: \[{ status: "active" }, { priority: "high" }] }Supported by: All except Vectorize, Couchbase`$not`Logical NOT{ price: { $not: { $lt: 100 } } }Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB`$nor`Logical NOR{ $nor: \[{ status: "deleted" }, { archived: true }] }Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB
+`$and`Logical AND{ $and: \[{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }Supported by: All except Vectorize, Couchbase`$or`Logical OR{ $or: \[{ status: "active" }, { priority: "high" }] }Supported by: All except Vectorize, Couchbase`$not`Logical NOT{ price: { $not: { $lt: 100 } } }Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB`$nor`Logical NOR{ $nor: \[{ status: "deleted" }, { archived: true }] }Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB
 
 ### Element Operators
 
@@ -46,7 +46,7 @@ const results = await store.query({
 
 ### Custom Operators
 
-`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB`$size`Array length check{ tags: { $size: { $gt: 2 } } }Supported by: Astra, libSQL, PgVector, MongoDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
+`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector, OracleDB`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB, OracleDB`$size`Array length check{ tags: { $size: 3 } }Supported by: Astra, libSQL, PgVector, MongoDB, OracleDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
 
 ## Common rules and restrictions
 
@@ -124,6 +124,14 @@ const results = await store.query({
 - Empty arrays in conditions are handled gracefully
 - Metadata is stored in a JSONB column for efficient querying
 
+### OracleDB
+
+- Metadata is stored as Oracle JSON alongside each `VECTOR` row
+- Scalar comparisons use `JSON_VALUE`, while array, existence, and element-match checks use `JSON_EXISTS`
+- `$regex` uses Oracle `REGEXP_LIKE`; string `$contains` uses case-insensitive `LIKE`
+- Nested fields are supported with dot notation and are converted to quoted Oracle JSON paths
+- User-provided metadata values are bound as parameters instead of interpolated into SQL
+
 ### PgVector
 
 - Full support for PostgreSQL's native JSON querying capabilities
@@ -211,6 +219,7 @@ const results = await store.query({
 - [Cloudflare Vectorize](https://mastra.ai/reference/vectors/vectorize)
 - [libSQL](https://mastra.ai/reference/vectors/libsql)
 - [MongoDB](https://mastra.ai/reference/vectors/mongodb)
+- [OracleDB](https://mastra.ai/reference/vectors/oracledb)
 - [PgStore](https://mastra.ai/reference/vectors/pg)
 - [Pinecone](https://mastra.ai/reference/vectors/pinecone)
 - [Qdrant](https://mastra.ai/reference/vectors/qdrant)

package/.docs/{guides → reference}/rag/overview.md

@@ -63,11 +63,11 @@ This example shows the essentials. Initialize a document and create chunks, then
 
 ## Document processing
 
-The basic building block of RAG is document processing. Documents can be chunked using strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](https://mastra.ai/guides/rag/chunking-and-embedding).
+The basic building block of RAG is document processing. Documents can be chunked using strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](https://mastra.ai/reference/rag/chunking-and-embedding).
 
 ## Vector storage
 
-Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/guides/rag/vector-databases).
+Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, OracleDB, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/reference/rag/vector-databases).
 
 ## More resources
 

package/.docs/{guides → reference}/rag/retrieval.md

@@ -436,6 +436,23 @@ export const ragAgent = new Agent({
 })
 ```
 
+**OracleDB**:
+
+```ts
+import { ORACLEDB_PROMPT } from '@mastra/oracledb'
+
+export const ragAgent = new Agent({
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${ORACLEDB_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+})
+```
+
 **S3Vectors**:
 
 ```ts
@@ -517,4 +534,4 @@ The re-ranked results combine vector similarity with semantic understanding to i
 
 For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/rag/rerankWithScorer) method.
 
-For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/guides/rag/graph-rag) documentation.
+For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/reference/rag/graph-rag-guide) documentation.

package/.docs/{guides → reference}/rag/vector-databases.md

@@ -78,6 +78,35 @@ await store.upsert({
 
 PostgreSQL with the pgvector extension is a good solution for teams already using PostgreSQL who want to minimize infrastructure complexity. For detailed setup instructions and best practices, see the [official pgvector repository](https://github.com/pgvector/pgvector).
 
+**OracleDB**:
+
+```ts
+import { OracleVector } from '@mastra/oracledb'
+
+const store = new OracleVector({
+  id: 'oracle-vector',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+
+await store.createIndex({
+  indexName: 'myCollection',
+  dimension: 1536,
+  indexConfig: { type: 'none' },
+})
+
+await store.upsert({
+  indexName: 'myCollection',
+  vectors: embeddings,
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
+```
+
+### Using Oracle Database Vector Search
+
+OracleDB stores embeddings in native `VECTOR` columns and metadata in Oracle JSON. Exact search is the default; HNSW and IVF indexes can be configured for tuned deployments.
+
 **Pinecone**:
 
 ```ts
@@ -378,7 +407,7 @@ await store.createIndex({
 
 The dimension size must match the output dimension of your chosen embedding model. Common dimension sizes are:
 
-- `OpenAI text-embedding-3-small`: 1536 dimensions (or custom, e.g., 256)
+- OpenAI `text-embedding-3-small`: 1536 dimensions (or custom, e.g., 256)
 - `Cohere embed-multilingual-v3`: 1024 dimensions
 - `VoyageAI voyage-3.5`: 1024 dimensions (or custom: 256, 512, 1024, 2048)
 - `Google gemini-embedding-001`: 768 dimensions (or custom)
@@ -410,6 +439,18 @@ Index names must:
 - Example: `my_index_123` is valid
 - Example: `my-index` is not valid (contains hyphen)
 
+**OracleDB**:
+
+Index names are logical Mastra names. OracleDB maps each logical index to a physical Oracle table internally.
+
+Logical index names must:
+
+- Be non-empty
+- Be 512 characters or fewer
+- Be stable for the lifetime of the vector index
+- Example: `my_collection_123` is valid
+- Example: `customer-support/docs:v1` is valid and is mapped to a safe Oracle table name
+
 **Pinecone**:
 
 Index names must:

package/.docs/reference/schedules/overview.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.50.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 `mastra.schedules` is the CRUD service for persisted cron schedules. Use it to create, list, update, pause, resume, manually run, and delete schedules for agents or workflows.
 
 For usage patterns and concepts, see [Schedules](https://mastra.ai/docs/long-running-agents/schedules).

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

@@ -72,10 +72,36 @@ handler: async params => {
 
 ## Return value
 
-Returns a `ServerRoute` object that can be registered with an adapter.
+Returns a `ServerRoute` object that can be registered with an adapter or passed to `server.apiRoutes` on the `Mastra` instance.
 
 ## Examples
 
+### Register through `server.apiRoutes`
+
+Routes created with `createRoute()` can be passed to `server.apiRoutes`. The adapter registers them with runtime validation, typed handler parameters, and generated OpenAPI metadata. See [Custom API routes](https://mastra.ai/docs/server/custom-api-routes) for details.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { createRoute } from '@mastra/server/server-adapter'
+import { z } from 'zod'
+
+const createItemRoute = createRoute({
+  method: 'POST',
+  path: '/items',
+  responseType: 'json',
+  bodySchema: z.object({
+    name: z.string(),
+  }),
+  handler: async ({ name }) => ({ id: 'new-id', name }),
+})
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [createItemRoute],
+  },
+})
+```
+
 ### GET route with path params
 
 ```typescript

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

@@ -22,6 +22,8 @@ registerApiRoute("/items/:itemId", { ... })
 
 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.
 
+> **Warning:** The default auth configuration protects `/api/*` and treats `/api`, `/api/auth/*` as public. When you change `apiPrefix`, those defaults no longer match and built-in routes fall outside the protected pattern. Update `server.auth.protected` and `server.auth.public` to reference the new prefix, and update any client code (including `MastraClient` `apiPrefix`) that hits `/api/*`.
+
 ### options
 
 **method** (`'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'`): HTTP method for the route

package/.docs/reference/signals/create-notification-inbox-tool.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 `createNotificationInboxTool()` creates a Mastra tool that lets an agent inspect and manage notification inbox records for the current thread.
 
 Use this tool with durable notification signals. For sending notification records, see [`Agent.sendNotificationSignal()`](https://mastra.ai/reference/agents/agent).

package/.docs/reference/signals/signal-provider.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Abstract base class for building signal providers. A signal provider monitors external sources (APIs, webhooks, event streams) and pushes notification signals into agent threads through a built-in subscription registry.
 
 Signal providers aren't processors by default. Providers that need to intercept agent execution return processors from `getInputProcessors()` or `getOutputProcessors()`. Providers that expose agent-callable tools return them from `getTools()`.

package/.docs/reference/signals/task-signal-provider.md

@@ -2,6 +2,8 @@
 
 # TaskSignalProvider
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Bundles the built-in task tools (`task_write`, `task_update`, `task_complete`, `task_check`) and the `TaskStateProcessor` behind a single agent registration. Use it to add a structured, durable task list to an agent without wiring the tools and processor separately.
 
 Extends [`SignalProvider`](https://mastra.ai/reference/signals/signal-provider). The task list is stored in the thread-scoped `tasks` storage domain (the source of truth) and projected onto the agent state-signal lane by the processor, so it survives observational-memory truncation without invalidating the prompt cache.

package/.docs/reference/signals/webhook-signal-provider.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Concrete signal provider for push-based event delivery. Routes incoming webhook payloads to subscribed agent threads by matching the payload against a configurable resource ID extractor.
 
 Extends [`SignalProvider`](https://mastra.ai/reference/signals/signal-provider) with public subscription management and a built-in `handleWebhook()` implementation.

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

@@ -338,7 +338,7 @@ const storage = new MastraCompositeStore({
 
 Observability data can quickly overwhelm general-purpose databases in production. A single agent interaction can generate hundreds of spans, and high-traffic applications can produce thousands of traces per day.
 
-**[ClickHouse](https://mastra.ai/reference/storage/clickhouse)** is recommended for production observability because it's optimized for high-volume, write-heavy analytics workloads. Use composite storage to route observability to ClickHouse while keeping other data in your primary database:
+**[ClickHouse](https://mastra.ai/integrations/databases/clickhouse)** is recommended for production observability because it's optimized for high-volume, write-heavy analytics workloads. Use composite storage to route observability to ClickHouse while keeping other data in your primary database:
 
 ```typescript
 import { MastraCompositeStore } from '@mastra/core/storage'
@@ -360,7 +360,7 @@ 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 haven't 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/integrations/databases/clickhouse) for details.
 
 ### Replicated ClickHouse for multi-replica clusters
 
@@ -392,6 +392,6 @@ const storage = new MastraCompositeStore({
 })
 ```
 
-Don't 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.
+Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side. See the [ClickHouse storage reference](https://mastra.ai/integrations/databases/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.
+> **Note:** 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/overview.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Storage overview
+# Storage
 
 Mastra storage is organized into domains. Each domain owns a set of tables or collections. Depending on your adapter and configuration, you may use all domains or only a subset.
 

package/.docs/reference/storage/retention.md

@@ -8,7 +8,7 @@ Storage grows without bound by default. Retention is an opt-in, age-based cleanu
 
 Retention covers **growth tables** only: tables that accumulate rows unbounded as a side effect of normal operation (conversation history, telemetry, job and run records, schedule fire history, event feeds). User-authored artifacts and config (agents, skills, workspaces, prompt blocks, datasets, schedule definitions, channel installations, and so on) grow with user intent and are edited or deleted explicitly, so they're not valid retention keys.
 
-The reference implementations are [libSQL](https://mastra.ai/reference/storage/libsql), [PostgreSQL](https://mastra.ai/reference/storage/postgresql), and [MongoDB](https://mastra.ai/reference/storage/mongodb). Other adapters keep rows forever until they implement retention.
+The reference implementations are [libSQL](https://mastra.ai/integrations/databases/libsql), [PostgreSQL](https://mastra.ai/integrations/databases/postgresql), and [MongoDB](https://mastra.ai/integrations/databases/mongodb). Other adapters keep rows forever until they implement retention.
 
 ## Usage example
 
@@ -238,11 +238,11 @@ Handing that free space back to the OS is a separate concern that Mastra doesn't
 
 For MongoDB, deleted documents are reused by future insertions. To reclaim disk space, run [`db.runCommand({ compact: "collection_name" })`](https://www.mongodb.com/docs/manual/reference/command/compact/) during a maintenance window.
 
-> **LibSQL and Turso:** [Turso Cloud](https://mastra.ai/reference/storage/libsql) manages storage compaction for you, so there's nothing to reclaim manually. This applies only to self-hosted libSQL files.
+> **LibSQL and Turso:** [Turso Cloud](https://mastra.ai/integrations/databases/libsql) manages storage compaction for you, so there's nothing to reclaim manually. This applies only to self-hosted libSQL files.
 
 ## Related
 
-- [libSQL storage](https://mastra.ai/reference/storage/libsql)
-- [PostgreSQL storage](https://mastra.ai/reference/storage/postgresql)
+- [libSQL storage](https://mastra.ai/integrations/databases/libsql)
+- [PostgreSQL storage](https://mastra.ai/integrations/databases/postgresql)
 - [Composite storage](https://mastra.ai/reference/storage/composite)
 - [Storage overview](https://mastra.ai/reference/storage/overview)

package/.docs/reference/streaming/ChunkType.md

@@ -310,7 +310,7 @@ Signals the completion of a processing step.
 
 **payload.messageId** (`string`): Optional message identifier
 
-**payload.stepResult** (`object`): Step execution result with reason, warnings, and continuation info
+**payload.stepResult** (`object`): Step execution result with reason, warnings, and continuation info. rawReason holds the provider's own finish reason when it reports one.
 
 **payload.output** (`object`): Output information including usage statistics
 
@@ -334,13 +334,13 @@ Contains raw data from the provider.
 
 ### finish
 
-Stream has completed successfully.
+Stream has completed.
 
 **type** (`"finish"`): Chunk type identifier
 
 **payload** (`FinishPayload`): Completion information
 
-**payload.stepResult** (`object`): Step execution result
+**payload.stepResult** (`object`): Step execution result. reason holds the normalized finish reason, and rawReason holds the provider's own finish reason when it reports one. A reason of "error" means the run failed.
 
 **payload.output** (`object`): Output information including usage
 

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

@@ -10,7 +10,7 @@ The `.stream()` method enables real-time streaming of responses from an agent wi
 const stream = await agent.stream('message for agent')
 ```
 
-> **Info:** **Model Compatibility**: This method is designed for V2 models. V1 models should use the [`.streamLegacy()`](https://mastra.ai/reference/streaming/agents/streamLegacy) method. The framework automatically detects your model version and will throw an error if there's a mismatch.
+> **Note:** **Model Compatibility**: This method is designed for V2 models. V1 models should use the [`.streamLegacy()`](https://mastra.ai/reference/streaming/agents/streamLegacy) method. The framework automatically detects your model version and will throw an error if there's a mismatch.
 
 ## Parameters
 

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

@@ -2,7 +2,7 @@
 
 # Agent.streamLegacy() (Legacy)
 
-> **Warning:** **Deprecated**: This method is deprecated and only works with V1 models. For V2 models, use the new [`.stream()`](https://mastra.ai/reference/streaming/agents/stream) method instead. See the [migration guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis) for details on upgrading.
+> **Warning:** **Deprecated**: This method is deprecated and only works with V1 models. For V2 models, use the new [`.stream()`](https://mastra.ai/reference/streaming/agents/stream) method instead. See the [migration guide](https://mastra.ai/reference/migrations/vnext-to-standard-apis) for details on upgrading.
 
 The `.streamLegacy()` method is the legacy version of the agent streaming API, used for real-time streaming of responses from V1 model agents. This method accepts messages and optional streaming options.
 
@@ -152,7 +152,7 @@ await agent.streamLegacy('message for agent', {
 
 ## Migration to new API
 
-> **Info:** The new `.stream()` method offers enhanced capabilities including AI SDK v5+ compatibility, better structured output handling, and improved callback system. See the [migration guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis) for detailed migration instructions.
+> **Note:** The new `.stream()` method offers enhanced capabilities including AI SDK v5+ compatibility, better structured-output handling, and improved callback system. See the [migration guide](https://mastra.ai/reference/migrations/vnext-to-standard-apis) for detailed migration instructions.
 
 ### Quick Migration Example
 
@@ -180,7 +180,7 @@ const result = await agent.stream('message', {
 
 ## Related
 
-- [Migration Guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis)
+- [Migration Guide](https://mastra.ai/reference/migrations/vnext-to-standard-apis)
 - [New .stream() method](https://mastra.ai/reference/streaming/agents/stream)
 - [Generating responses](https://mastra.ai/docs/agents/overview)
 - [Streaming responses](https://mastra.ai/docs/agents/overview)

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

@@ -32,7 +32,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-> **Info:** `streamUntilIdle()` requires both a [`BackgroundTaskManager`](https://mastra.ai/reference/configuration) and a [memory](https://mastra.ai/docs/memory/overview) backend. Without either, it uses a plain `agent.stream()` call.
+> **Note:** `streamUntilIdle()` requires both a [`BackgroundTaskManager`](https://mastra.ai/reference/configuration) and a [memory](https://mastra.ai/docs/memory/overview) backend. Without either, it uses a plain `agent.stream()` call.
 
 ## Parameters
 

package/.docs/reference/templates/overview.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Overview
+# Templates
 
 This reference explains how to use existing Mastra templates and create your own. It also covers contributing templates to the community ecosystem.
 

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

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.38.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 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).
@@ -62,7 +64,7 @@ export const shopAgent = new Agent({
 
 **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. Transports that declare requiresSandbox: false (such as IsolatedVmCodeModeTransport) run without a sandbox.
+**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. Transports that declare requiresSandbox: false (such as IsolatedVmCodeModeTransport and QuickJsCodeModeTransport) run without a sandbox.
 
 ## Returns
 

package/.docs/reference/tools/isolated-vm-transport.md

@@ -2,7 +2,7 @@
 
 # IsolatedVmCodeModeTransport
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 The `IsolatedVmCodeModeTransport` class runs [Code mode](https://mastra.ai/docs/agents/code-mode) programs in an in-process V8 isolate, backed by [isolated-vm](https://github.com/laverdet/isolated-vm). The isolate is the execution boundary, so no workspace sandbox is required: the program has no filesystem, network, process, or module access. Its only capabilities are the `external_*` functions, which call back into the real tools on the host.
 

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

@@ -244,6 +244,57 @@ const res = await agent.stream(prompt, {
 })
 ```
 
+### `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).
+
+Unlike `listTools()`, the result contains no functions or references to a live client, so it can be passed through `JSON.stringify` and cached in Redis, a database, or a build artifact. Each definition holds the data from the MCP `tools/list` response (name, description, input schema, output schema, annotations, and `_meta`), plus the server name, version, and instructions captured at discovery time.
+
+```typescript
+const definitions = await mcp.listToolDefinitions()
+
+await cache.set('mcp-tools', JSON.stringify(definitions))
+```
+
+### `listToolDefinitionsWithErrors()`
+
+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.
+
+```typescript
+const { definitions, errors } = await mcp.listToolDefinitionsWithErrors()
+
+if (Object.keys(errors).length === 0) {
+  await cache.set('mcp-tools', JSON.stringify(definitions))
+}
+```
+
+### `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.
+
+The returned tool behaves exactly like one from `listTools()`, with the same strict-mode metadata, approval policy, structured content handling, tool error handling, and reconnect behavior.
+
+```typescript
+const definitions = JSON.parse(await cache.get('mcp-tools'))
+
+const tool = await mcp.toolFromDefinition({
+  serverName: 'weather',
+  definition: definitions.weather.getForecast,
+})
+```
+
+### `toolsFromDefinitions()`
+
+Rebuilds an entire cached catalog into a namespaced tool map, without connecting. This is the cached counterpart to `listTools()`. It produces the same `serverName_toolName` keys, so you can reconstruct an agent's tool map on a cold start, and connections only open for the servers whose tools are actually called.
+
+Servers present in the catalog but no longer configured on the client are skipped, so a stale cached manifest degrades gracefully.
+
+```typescript
+const definitions = JSON.parse(await cache.get('mcp-tools'))
+
+new Agent({ id: 'agent', tools: await mcp.toolsFromDefinitions({ definitions }) })
+```
+
 ### `getServerInstructions()`
 
 Returns the instructions currently known for each configured MCP server. Servers that haven't connected yet, or don't advertise instructions, return `undefined`.

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

@@ -929,7 +929,7 @@ Notification methods (`resources.notifyListChanged()`, `prompts.notifyListChange
 
 ## Examples
 
-For practical examples of setting up and deploying an MCPServer, see the [Publishing an MCP Server guide](https://mastra.ai/guides/guide/publishing-mcp-server).
+For a practical example of packaging a stdio server, see [Publish a stdio server package](https://mastra.ai/docs/mcp/overview).
 
 The example at the beginning of this page also demonstrates how to instantiate `MCPServer` with both tools and agents.
 

package/.docs/reference/tools/quickjs-transport.md

@@ -0,0 +1,92 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# QuickJsCodeModeTransport
+
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
+The `QuickJsCodeModeTransport` class runs [Code mode](https://mastra.ai/docs/agents/code-mode) programs in an in-process [QuickJS](https://bellard.org/quickjs/) runtime compiled to WebAssembly. The runtime is the execution boundary, so no workspace sandbox is required: the program has no filesystem, network, process, or module access. Its only capabilities are the `external_*` functions, which call back into the real tools on the host.
+
+Unlike [`IsolatedVmCodeModeTransport`](https://mastra.ai/reference/tools/isolated-vm-transport), this transport installs no native binaries and needs no Node.js flags, so it runs on serverless platforms that disallow both. The tradeoff is speed: see [Choosing a transport](#choosing-a-transport).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/quickjs
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/quickjs
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/quickjs
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/quickjs
+```
+
+The package contains the WebAssembly module, so installing it copies files and runs nothing else.
+
+## Usage
+
+Pass the transport as the second argument to `createCodeMode()`. No `sandbox` is needed:
+
+```typescript
+import { createCodeMode } from '@mastra/core/tools'
+import { QuickJsCodeModeTransport } from '@mastra/quickjs'
+
+const { tool, instructions } = createCodeMode(
+  { tools: { getTopProducts, getProductRatings } },
+  new QuickJsCodeModeTransport({ memoryLimitMb: 128 }),
+)
+```
+
+## Constructor parameters
+
+**options** (`QuickJsCodeModeTransportOptions`): Configuration for the QuickJS runtime.
+
+**options.memoryLimitMb** (`number`): Runtime heap limit in MiB. A program that exceeds the limit is terminated and the tool returns an error result.
+
+**options.maxStackSizeBytes** (`number`): Runtime stack limit in bytes. A program that exceeds the limit, usually through runaway recursion, is terminated and the tool returns an error result.
+
+**options.module** (`QuickJSWASMModule`): A preloaded QuickJS WebAssembly module. Supply one to control when the module is loaded, or to share a single module across transports. Loaded on first run when omitted.
+
+## Choosing a transport
+
+All three transports enforce the same allow-list, tool validation, and tracing on the host. They differ in what the program itself can reach and what the host has to provide.
+
+|                     | `StdioCodeModeTransport`       | `IsolatedVmCodeModeTransport`                | `QuickJsCodeModeTransport`  |
+| ------------------- | ------------------------------ | -------------------------------------------- | --------------------------- |
+| Isolation boundary  | Workspace sandbox              | V8 isolate                                   | QuickJS WebAssembly runtime |
+| Requires a sandbox  | Yes                            | No                                           | No                          |
+| Native binary       | Node.js runtime in the sandbox | Yes                                          | No                          |
+| Node.js flags       | None                           | `--no-node-snapshot` on Node.js 20 and later | None                        |
+| Runs in the browser | No                             | No                                           | Yes                         |
+| Execution speed     | Fastest                        | Fast                                         | Slowest                     |
+
+Choose `QuickJsCodeModeTransport` when the host can't install native addons or set Node.js flags, which is common on serverless platforms. Choose `IsolatedVmCodeModeTransport` when the host allows both and programs do heavy computation.
+
+The speed difference is in the program body, not the tool calls. QuickJS interprets rather than JIT-compiles, so a compute-heavy loop can run tens of times slower than in a V8 isolate, while a program that mostly awaits `external_*` calls performs about the same because the time goes to the tools. Code Mode programs are usually the second kind.
+
+## How it works
+
+Each run creates a fresh QuickJS runtime with its own heap. TypeScript is stripped on the host with [ts-blank-space](https://github.com/bloomberg/ts-blank-space), which erases type annotations without a native compiler, then the program is evaluated inside the runtime. Every `external_*` call crosses the boundary as JSON strings in both directions, so no host object references leak into model-authored code.
+
+An `external_*` call returns a pending promise to the program and hands control straight back to the host, so many calls can be in flight at once and `Promise.all` behaves as expected.
+
+The `timeout` configured on `createCodeMode()` applies to both asynchronous hangs and synchronous infinite loops, and the runtime is disposed after every run.
+
+## Related
+
+- [Code mode](https://mastra.ai/docs/agents/code-mode)
+- [createCodeMode() reference](https://mastra.ai/reference/tools/create-code-mode)
+- [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport)

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

@@ -4,7 +4,7 @@
 
 The ChromaVector class provides vector search using [Chroma](https://docs.trychroma.com/docs/overview/getting-started), an open-source embedding database. It offers efficient vector search with metadata filtering and hybrid search capabilities.
 
-> **Info:**
+> **Note:**
 >
 > **Chroma Cloud**
 >

package/.docs/reference/vectors/convex.md

@@ -36,7 +36,7 @@ bun add @mastra/convex@latest
 
 ## Convex setup
 
-Before using `ConvexVector`, you need to set up the Convex schema and storage handler. See [Convex Storage Setup](https://mastra.ai/reference/storage/convex) for setup instructions.
+Before using `ConvexVector`, you need to set up the Convex schema and storage handler. See [Convex Storage Setup](https://mastra.ai/integrations/databases/convex) for setup instructions.
 
 ## Constructor options
 
@@ -419,6 +419,6 @@ Use an external vector database when you need runtime-defined index creation at
 
 ## Related
 
-- [Convex Storage](https://mastra.ai/reference/storage/convex)
+- [Convex Storage](https://mastra.ai/integrations/databases/convex)
 - [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
 - [Convex Documentation](https://docs.convex.dev/)