@mastra/mcp-docs-server 1.2.15-alpha.7 → 1.2.15

package/.docs/{guides → reference}/migrations/upgrade-to-v1/tracing.md

@@ -6,7 +6,7 @@ The observability system has been restructured in v1 with a dedicated `@mastra/o
 
 > **Observability data stops flowing on upgrade:** If you upgrade Mastra packages to v1 without migrating your `telemetry:` config to `observability:`, the old config is ignored at runtime. Your service will start cleanly with no error, but **no traces, logs, or metrics will be sent anywhere**. If you were sending data to Mastra Cloud, the dashboard will go empty.
 >
-> Complete this migration in the same change that bumps your Mastra packages, and verify traces appear in [Mastra Studio](https://mastra.ai/docs/studio/observability) before considering the upgrade complete. If you previously hosted on Mastra Cloud, also follow the [Mastra Cloud migration guide](https://mastra.ai/guides/migrations/mastra-cloud). The new platform requires a new access token and a Studio project before `MastraPlatformExporter` can route data to it.
+> Complete this migration in the same change that bumps your Mastra packages, and verify traces appear in [Mastra Studio](https://mastra.ai/docs/studio/observability) before considering the upgrade complete. If you previously hosted on Mastra Cloud, also follow the [Mastra Cloud migration guide](https://mastra.ai/reference/migrations/mastra-cloud). The new platform requires a new access token and a Studio project before `MastraPlatformExporter` can route data to it.
 
 > **Exporter rename:** `MastraPlatformExporter` (sends data to Mastra platform) replaces the previous `CloudExporter`, and `MastraStorageExporter` (persists data to Mastra Storage) replaces the previous `DefaultExporter`. The original classes remain available from `@mastra/observability` and behave identically, but they're deprecated. New code should use `MastraPlatformExporter` and `MastraStorageExporter`. Existing imports of `CloudExporter` or `DefaultExporter` continue to work until they're removed in a future major version.
 
@@ -354,14 +354,14 @@ No separate instrumentation files or special startup flags required.
 
 If you were using OTEL-based telemetry with specific providers in 0.x, here's how to configure them in v1:
 
-| Provider                                                  | Exporter          | Guide                                                                           | Reference                                                                           |
-| --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| Arize AX, Arize Phoenix                                   | **Arize**         | [Guide](https://mastra.ai/docs/observability/integrations/exporters/arize)      | [Reference](https://mastra.ai/reference/observability/tracing/exporters/arize)      |
-| Braintrust                                                | **Braintrust**    | [Guide](https://mastra.ai/docs/observability/integrations/exporters/braintrust) | [Reference](https://mastra.ai/reference/observability/tracing/exporters/braintrust) |
-| Langfuse                                                  | **Langfuse**      | [Guide](https://mastra.ai/docs/observability/integrations/exporters/langfuse)   | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langfuse)   |
-| LangSmith                                                 | **LangSmith**     | [Guide](https://mastra.ai/docs/observability/integrations/exporters/langsmith)  | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langsmith)  |
-| Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL | **OpenTelemetry** | [Guide](https://mastra.ai/docs/observability/integrations/exporters/otel)       | [Reference](https://mastra.ai/reference/observability/tracing/exporters/otel)       |
-| LangWatch                                                 | \<coming soon>    | -                                                                               | -                                                                                   |
+| Provider                                                  | Exporter          | Guide                                                               | Reference                                                                           |
+| --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Arize AX, Arize Phoenix                                   | **Arize**         | [Guide](https://mastra.ai/integrations/observability/arize)         | [Reference](https://mastra.ai/reference/observability/tracing/exporters/arize)      |
+| Braintrust                                                | **Braintrust**    | [Guide](https://mastra.ai/integrations/observability/braintrust)    | [Reference](https://mastra.ai/reference/observability/tracing/exporters/braintrust) |
+| Langfuse                                                  | **Langfuse**      | [Guide](https://mastra.ai/integrations/observability/langfuse)      | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langfuse)   |
+| LangSmith                                                 | **LangSmith**     | [Guide](https://mastra.ai/integrations/observability/langsmith)     | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langsmith)  |
+| Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL | **OpenTelemetry** | [Guide](https://mastra.ai/integrations/observability/opentelemetry) | [Reference](https://mastra.ai/reference/observability/tracing/exporters/otel)       |
+| LangWatch                                                 | \<coming soon>    | -                                                                   | -                                                                                   |
 
 ### Installation
 
@@ -417,4 +417,4 @@ yarn add @mastra/otel-exporter@latest
 bun add @mastra/otel-exporter@latest
 ```
 
-Plus the required protocol package for your provider (see [OTEL guide](https://mastra.ai/docs/observability/integrations/exporters/otel)).
+Plus the required protocol package for your provider (see [OTEL guide](https://mastra.ai/integrations/observability/opentelemetry)).

package/.docs/reference/observability/tracing/bridges/datadog.md

@@ -157,7 +157,7 @@ const mastra = new Mastra({
 
 The DatadogBridge requires `dd-trace` to be initialized before any other imports so its auto-instrumentation can patch HTTP, database, and framework libraries at load time.
 
-See the [DatadogBridge Guide](https://mastra.ai/docs/observability/integrations/bridges/datadog) for complete setup instructions, including dd-trace initialization, bundler externals, and agent configuration.
+See the [DatadogBridge Guide](https://mastra.ai/integrations/observability/datadog) for complete setup instructions, including dd-trace initialization, bundler externals, and agent configuration.
 
 ## Span mapping
 
@@ -208,6 +208,6 @@ The bridge reads configuration from these environment variables:
 
 ## Related
 
-- [DatadogBridge Guide](https://mastra.ai/docs/observability/integrations/bridges/datadog) - Setup guide with examples
+- [DatadogBridge Guide](https://mastra.ai/integrations/observability/datadog) - Setup guide with examples
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - General tracing concepts
 - [DatadogExporter Reference](https://mastra.ai/reference/observability/tracing/exporters/datadog) - LLM Observability only, no `dd-trace` APM

package/.docs/reference/observability/tracing/bridges/otel.md

@@ -120,7 +120,7 @@ const mastra = new Mastra({
 
 The OtelBridge requires an active OpenTelemetry SDK to function. The bridge reads from OTEL's ambient context.
 
-See the [OtelBridge Guide](https://mastra.ai/docs/observability/integrations/bridges/otel) for complete setup instructions, including how to configure OTEL instrumentation and run your application.
+See the [OtelBridge Guide](https://mastra.ai/integrations/observability/opentelemetry) for complete setup instructions, including how to configure OTEL instrumentation and run your application.
 
 ## Tags support
 
@@ -150,6 +150,6 @@ This format ensures compatibility with all OTEL-compatible backends and collecto
 
 ## Related
 
-- [OtelBridge Guide](https://mastra.ai/docs/observability/integrations/bridges/otel): Setup guide with examples
+- [OtelBridge Guide](https://mastra.ai/integrations/observability/opentelemetry): Setup guide with examples
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): General tracing concepts
 - [OtelExporter Reference](https://mastra.ai/reference/observability/tracing/exporters/otel): OTEL exporter for sending traces

package/.docs/reference/observability/tracing/exporters/arize.md

@@ -138,6 +138,6 @@ Tags are stored using the OpenInference `tag.tags` attribute:
 
 ## Related
 
-- [ArizeExporter Documentation](https://mastra.ai/docs/observability/integrations/exporters/arize)
+- [ArizeExporter Documentation](https://mastra.ai/integrations/observability/arize)
 - [Phoenix Documentation](https://docs.arize.com/phoenix)
 - [Arize AX Documentation](https://docs.arize.com/)

package/.docs/reference/observability/tracing/exporters/arthur.md

@@ -119,6 +119,6 @@ Tags are stored using the OpenInference `tag.tags` attribute:
 
 ## Related
 
-- [ArthurExporter Documentation](https://mastra.ai/docs/observability/integrations/exporters/arthur)
+- [ArthurExporter Documentation](https://mastra.ai/integrations/observability/arthur)
 - [Arthur Engine documentation](https://docs.arthur.ai/)
 - [Arthur Engine repository](https://github.com/arthur-ai/arthur-engine)

package/.docs/reference/observability/tracing/exporters/confident-ai.md

@@ -4,7 +4,7 @@
 
 Sends Tracing data to [Confident AI](https://www.confident-ai.com/) for evaluation and observability. Exported by `@mastra/deepeval`, which builds on the DeepEval SDK.
 
-See [Confident AI exporter](https://mastra.ai/docs/observability/integrations/exporters/confident-ai) for setup and usage.
+See [Confident AI exporter](https://mastra.ai/integrations/observability/confident-ai) for setup and usage.
 
 ## Constructor
 

package/.docs/reference/observability/tracing/exporters/datadog.md

@@ -4,7 +4,7 @@
 
 Sends Tracing data to Datadog's LLM Observability product for monitoring and analytics.
 
-> **Info:** If you also use `dd-trace` APM auto-instrumentation and need it correctly parented under Mastra spans, use the [DatadogBridge](https://mastra.ai/reference/observability/tracing/bridges/datadog) instead. The exporter sends LLM Observability data after execution completes, so it doesn't participate in `dd-trace`'s live scope.
+> **Note:** If you also use `dd-trace` APM auto-instrumentation and need it correctly parented under Mastra spans, use the [DatadogBridge](https://mastra.ai/reference/observability/tracing/bridges/datadog) instead. The exporter sends LLM Observability data after execution completes, so it doesn't participate in `dd-trace`'s live scope.
 
 ## Constructor
 

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

@@ -177,6 +177,18 @@ The exporter batches tracing spans, logs, metrics, scores, and feedback for effi
 
 Errors raised by `MastraPlatformExporter` use the `MASTRA_PLATFORM_EXPORTER_*` `id` prefix. The deprecated `CloudExporter` continues to emit `CLOUD_EXPORTER_*` `id`s.
 
+### Quota pause
+
+When an organization has exhausted its observability quota, the Mastra platform rejects publish requests with `402 Payment Required` plus the `x-mastra-observability: disabled` header. When the exporter sees a `402` (or the header) on any publish route, it:
+
+- Drops the rejected batch without retrying it
+- Pauses all five signal types (traces, logs, metrics, scores, feedback) and drops buffered and new events instead of sending them
+- Logs a warning that telemetry is paused
+- Probes the platform periodically with an empty batch, using the interval from the `x-mastra-observability-retry-after` header (seconds), or every 5 minutes if the header is absent
+- Resumes exporting automatically and logs a warning once the platform stops rejecting with `402`
+
+The probe timer doesn't keep the Node.js process alive, so short-lived and serverless processes exit normally while paused.
+
 ### Endpoint routing
 
 - Base origins derive signal endpoints automatically

package/.docs/reference/observability/tracing/exporters/otel.md

@@ -200,6 +200,6 @@ Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute
 
 ## Related
 
-- [OtelExporter Guide](https://mastra.ai/docs/observability/integrations/exporters/otel): Setup guide with provider configurations
-- [OtelBridge](https://mastra.ai/docs/observability/integrations/bridges/otel): For bidirectional OTEL context integration
+- [OtelExporter Guide](https://mastra.ai/integrations/observability/opentelemetry): Setup guide with provider configurations
+- [OtelBridge](https://mastra.ai/integrations/observability/opentelemetry): For bidirectional OTEL context integration
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): General tracing concepts

package/.docs/reference/processors/pii-detector.md

@@ -42,6 +42,8 @@ const processor = new PIIDetector({
 
 **options.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., { openai: { reasoningEffort: 'low' } })
 
+**options.onDetection** (`(event: PIIDetectionEvent) => void | Promise<void>`): Called whenever a detection result is produced, with detectionResult, the analyzed input, whether it was flagged, and the strategyApplied (the configured strategy when flagged, otherwise none). Fires for every analyzed message in processInput and processOutputResult, and for every LLM buffer flush during streaming; the streaming regex pass only reports when PII is found. Errors thrown by the callback are logged and ignored
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'pii-detector'

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

@@ -38,6 +38,8 @@ const processor = new PromptInjectionDetector({
 
 **options.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., { openai: { reasoningEffort: 'low' } })
 
+**options.onDetection** (`(event: PromptInjectionDetectionEvent) => void | Promise<void>`): Called for every analyzed message with detectionResult, the analyzed input, whether it was flagged, and the strategyApplied (the configured strategy when flagged, otherwise none). Use it to emit custom metrics. Errors thrown by the callback are logged and ignored
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'prompt-injection-detector'

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

@@ -43,6 +43,24 @@ const filter = new RegexFilterProcessor({
 })
 ```
 
+Raise the streaming carryover window for long custom matches (e.g. a fixed-length secret or a value that only matches once its closing delimiter arrives):
+
+```typescript
+import { RegexFilterProcessor } from '@mastra/core/processors'
+
+const filter = new RegexFilterProcessor({
+  rules: [
+    {
+      name: 'armored-key',
+      pattern: /-----BEGIN KEY-----[A-Z]+-----END KEY-----/g,
+      replacement: '[KEY]',
+    },
+  ],
+  strategy: 'redact',
+  streamCarryoverSize: 256,
+})
+```
+
 Attach to an agent:
 
 ```typescript
@@ -80,6 +98,8 @@ const agent = new Agent({
 
 **includeRedactedValues** (`boolean`): Include the text that was redacted in each report entry. Off by default, because the values are the data the processor removes. (Default: `false`)
 
+**streamCarryoverSize** (`number`): Trailing characters the streaming redact path holds back between chunks, so a match split across a chunk boundary is redacted whole. The default covers every built-in preset with a wide margin. Raise it for custom rules whose matches stay invisible to the rule until they complete, such as a fixed-length secret or a value with a closing delimiter, when such a match can be longer than the window. (Default: `128`)
+
 ## Returns
 
 **id** (`'regex-filter'`): Processor identifier.

package/.docs/reference/processors/response-cache.md

@@ -2,6 +2,8 @@
 
 # ResponseCache
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 `ResponseCache` is an input processor that caches LLM responses on the request/response boundary inside the agentic loop. It hooks into `processLLMRequest` for cache lookup and short-circuits on a hit. It uses `processLLMResponse` to write the completed response.
 
 The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model (i.e. _after_ memory has loaded and earlier input processors have transformed the prompt) so two users with different memory contexts produce different cache keys. Each step in an agentic tool loop is independently cached.

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

@@ -29,6 +29,8 @@ const toolSearch = new ToolSearchProcessor({
 
 **options.tools** (`Record<string, Tool>`): All tools that can be searched and loaded dynamically. These tools are not immediately available to the agent — they must be discovered via search and loaded on demand.
 
+**options.includeResolvedTools** (`boolean`): Also make the tools the agent resolved for this request (MCP tools requiring the caller's credentials, or anything returned by a dynamic tools function) searchable, and withhold them from the prompt until the agent loads them. The meta-tools are never withheld. Request-resolved tools are indexed per request, so each request searches and loads its own tool instances.
+
 **options.search** (`{ topK?: number; minScore?: number; autoLoad?: boolean }`): Configuration for the search behavior.
 
 **options.search.topK** (`number`): Maximum number of tools to return in search results.
@@ -120,7 +122,37 @@ The `phase` value describes where the filter is being applied:
 - `load`: Blocks `load_tool` from loading disallowed tools.
 - `active`: Hides already-loaded tools from the current request if they're no longer allowed.
 
-If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The `search_tools` meta-tool is always available. `load_tool` is available unless `search.autoLoad` is enabled. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`.
+If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The `search_tools` meta-tool is always available. `load_tool` is available unless `search.autoLoad` is enabled. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`, or enable `includeResolvedTools`.
+
+## Searching request-resolved tools
+
+The `tools` option is fixed at construction, so you can't list tools that only exist per request (MCP tools that need the caller's credentials, or anything returned by a dynamic `tools` function). By default those tools bypass search and occupy prompt space on every turn.
+
+Set `includeResolvedTools: true` to index them for the request and withhold them from the prompt until the agent loads them:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ToolSearchProcessor } from '@mastra/core/processors'
+
+const toolSearch = new ToolSearchProcessor({
+  tools: staticTools,
+  includeResolvedTools: true,
+})
+
+const agent = new Agent({
+  id: 'mcp-agent',
+  name: 'mcp-agent',
+  instructions: 'Search for a tool when you need a capability you do not have.',
+  model: 'openai/gpt-5.6-sol',
+  // Resolved per request, then searchable alongside staticTools
+  tools: async ({ requestContext }) => mcpClient.getTools(requestContext.get('userToken')),
+  inputProcessors: [toolSearch],
+})
+```
+
+Each request is indexed on its own, so a tool loaded by one caller never resolves to another caller's instance of the same tool name.
+
+This option applies to every tool resolved for the request, including memory, workspace, skill, and browser tools. Only the `search_tools` and `load_tool` meta-tools stay in the prompt, so any tool the agent relies on implicitly must be found through search before it can be called.
 
 ## Extended usage example
 

package/.docs/reference/pubsub/lease-provider.md

@@ -130,4 +130,4 @@ When the configured pub/sub backend doesn't implement `LeaseProvider`, the runti
 - [PubSub](https://mastra.ai/reference/pubsub/base): The event delivery contract, separate from leasing
 - [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams): The built-in backend that implements `LeaseProvider`
 - [Signals](https://mastra.ai/docs/long-running-agents/signals): The runtime that uses leasing to coordinate thread execution across processes
-- [Channels](https://mastra.ai/docs/capabilities/channels/overview): Uses leasing to coordinate agent runs in serverless and multi-instance deployments
+- [Channels](https://mastra.ai/docs/capabilities/channels): Uses leasing to coordinate agent runs in serverless and multi-instance deployments

package/.docs/{guides → reference}/rag/chunking-and-embedding.md

@@ -5,7 +5,9 @@
 Before processing, create a MDocument instance from your content. You can initialize it from different formats:
 
 ```ts
-const docFromText = MDocument.fromText('Your plain text content...')
+import { MDocument } from '@mastra/rag'
+
+const doc = MDocument.fromText('Your plain text content...')
 const docFromHTML = MDocument.fromHTML('<html>Your HTML content...</html>')
 const docFromMarkdown = MDocument.fromMarkdown('# Your Markdown content...')
 const docFromJSON = MDocument.fromJSON(`{ "key": "value" }`)
@@ -59,7 +61,7 @@ For markdown documents where preserving the semantic relationships between secti
 const chunks = await doc.chunk({
   strategy: 'semantic-markdown',
   joinThreshold: 500,
-  modelName: 'gpt-3.5-turbo',
+  modelName: 'gpt-5',
 })
 ```
 
@@ -129,51 +131,46 @@ const { embeddings } = await embedMany({
 
 ## Example: Complete pipeline
 
-Here's an example showing document processing and embedding generation with both providers:
+Here's an example showing document processing, embedding generation, and vector storage:
 
 ```ts
-import { embedMany } from 'ai'
-
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+import { PgVector } from '@mastra/pg'
 import { MDocument } from '@mastra/rag'
+import { embedMany } from 'ai'
 
-// Initialize document
 const doc = MDocument.fromText(`
   Climate change poses significant challenges to global agriculture.
   Rising temperatures and changing precipitation patterns affect crop yields.
 `)
 
-// Create chunks
 const chunks = await doc.chunk({
   strategy: 'recursive',
   maxSize: 256,
   overlap: 50,
 })
 
-// Generate embeddings with OpenAI
-import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
-
 const { embeddings } = await embedMany({
   model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
   values: chunks.map(chunk => chunk.text),
 })
 
-// OR
+const vectorStore = new PgVector({
+  id: 'pg-vector',
+  connectionString: process.env.POSTGRES_CONNECTION_STRING,
+})
 
-// Generate embeddings with Cohere
-const { embeddings } = await embedMany({
-  model: 'cohere/embed-english-v3.0',
-  values: chunks.map(chunk => chunk.text),
+await vectorStore.createIndex({
+  indexName: 'embeddings',
+  dimension: 1536,
 })
 
-// Store embeddings in your vector database
 await vectorStore.upsert({
   indexName: 'embeddings',
   vectors: embeddings,
 })
 ```
 
-##
-
 For more examples of different chunking strategies and embedding configurations, see:
 
 - [Chunk Reference](https://mastra.ai/reference/rag/chunk)
@@ -181,5 +178,5 @@ For more examples of different chunking strategies and embedding configurations,
 
 For more details on vector databases and embeddings, see:
 
-- [Vector Databases](https://mastra.ai/guides/rag/vector-databases)
+- [Vector Databases](https://mastra.ai/reference/rag/vector-databases)
 - [Embedding API Reference](https://mastra.ai/reference/rag/embeddings)

package/.docs/reference/rag/database-config.md

@@ -275,5 +275,5 @@ const vectorTool = createVectorQueryTool({
 ## Related
 
 - [createVectorQueryTool()](https://mastra.ai/reference/tools/vector-query-tool)
-- [Hybrid Vector Search](https://mastra.ai/guides/rag/retrieval)
+- [Hybrid Vector Search](https://mastra.ai/reference/rag/retrieval)
 - [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

package/.docs/{guides/rag/graph-rag.md → reference/rag/graph-rag-guide.md}

@@ -14,7 +14,7 @@ GraphRAG is particularly effective when:
 - Understanding connections between concepts is important
 - Simple vector similarity misses important contextual relationships
 
-For straightforward semantic search without relationship traversal, use [standard retrieval methods](https://mastra.ai/guides/rag/retrieval).
+For straightforward semantic search without relationship traversal, use [standard retrieval methods](https://mastra.ai/reference/rag/retrieval).
 
 ## How GraphRAG works
 

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