@mastra/mcp-docs-server 1.2.16-alpha.3 → 1.2.16-alpha.6

package/.docs/reference/migrations/upgrade-to-v1/storage.md

@@ -93,7 +93,7 @@ USING snapshot::jsonb;
 
 ### Storage composition in `MastraCompositeStore`
 
-`MastraCompositeStore` can now compose storage domains from different adapters. Use it when you need different databases for different purposes - for example, PostgreSQL for memory and workflows, but a specialized database for observability.
+`MastraCompositeStore` can now compose storage domains from different adapters. Use it when different purposes require different databases, such as PostgreSQL for memory and workflows with a specialized database for observability.
 
 ```typescript
 import { MastraCompositeStore } from '@mastra/core/storage'
@@ -386,7 +386,7 @@ To migrate, use the memory store, remove format parameters, and update code to w
 + const saved = saveResult?.messages; // MastraDBMessage[]
 ```
 
-### Vector store API from positional to named arguments
+### Vector store API from positional arguments to arguments by name
 
 All vector store methods now use an arguments object instead of positional arguments. This makes each value's purpose visible at the call site and lets method signatures evolve without relying on argument order.
 
@@ -430,7 +430,7 @@ To migrate, rename the methods and pass an arguments object.
 
 ### PGVector constructor from connection string to object
 
-The PGVector constructor now requires object parameters instead of a connection string. This change provides a more consistent API across all storage adapters.
+The PGVector constructor now requires object parameters instead of a connection string. Object parameters align the API across storage adapters.
 
 To migrate, pass the connection string as an object property.
 
@@ -484,7 +484,7 @@ const pgStore = new PostgresStore({
 
 ### Score storage methods to `listScoresBy*` pattern
 
-Score storage APIs have been renamed to follow the `listScoresBy*` pattern. This change provides consistency with the broader API naming conventions.
+Score storage APIs have been renamed to follow the `listScoresBy*` pattern. The new names follow the broader API naming conventions.
 
 To migrate, update method names from `getScores` to `listScoresByScorerId` and related variants.
 
@@ -500,7 +500,7 @@ To migrate, update method names from `getScores` to `listScoresByScorerId` and r
 
 ### Non-paginated storage functions
 
-Non-paginated storage functions have been removed in favor of paginated versions. All list operations now use pagination, though you can fetch all records with `perPage: false`. This change provides consistency across the API and prevents accidental loading of large datasets.
+Non-paginated storage functions have been removed in favor of paginated versions. All list operations now use pagination, though you can fetch all records with `perPage: false`. Pagination aligns list operations across the API and prevents accidental loading of large datasets.
 
 To migrate, use paginated methods via domain stores. For fetching all records, use `perPage: false`.
 

package/.docs/reference/migrations/upgrade-to-v1/tools.md

@@ -32,7 +32,7 @@ createTool({
 
 ### `createTool` context properties organization
 
-Context properties in `createTool` are now organized into namespaces. Agent-specific properties are under `context.agent`, workflow-specific properties are under `context.workflow`, and MCP-specific properties are under `context.mcp`. This change provides better organization and clearer API surface.
+Context properties in `createTool` are now organized into namespaces. Agent-specific properties are under `context.agent`, workflow-specific properties are under `context.workflow`, and MCP-specific properties are under `context.mcp`. The namespaces organize these properties under a clearer API surface.
 
 For tools that are executed inside an agent, access agent-specific properties through `context.agent`.
 

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

@@ -78,7 +78,7 @@ Force-flushes any buffered LLM Observability data to Datadog without shutting do
 async shutdown(): Promise<void>
 ```
 
-Force-finishes any APM spans that weren't properly closed, flushes pending LLM Observability data, disables the LLM Observability integration, and clears all internal state.
+Force-finishes any APM spans that weren't properly closed and flushes pending LLM Observability data. It then disables the integration and clears all internal state.
 
 ## Usage examples
 

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

@@ -146,7 +146,7 @@ Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute:
 }
 ```
 
-This format ensures compatibility with all OTEL-compatible backends and collectors.
+The format is compatible with all OTEL-compatible backends and collectors.
 
 ## Related
 

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

@@ -2,7 +2,7 @@
 
 # ArizeExporter
 
-Sends Tracing data to Arize Phoenix, Arize AX, or any OpenTelemetry-compatible observability platform that supports OpenInference semantic conventions.
+Sends Tracing data to Arize Phoenix or Arize AX, as well as any OpenTelemetry-compatible observability platform that supports OpenInference semantic conventions.
 
 ## Constructor
 

package/.docs/reference/observability/tracing/exporters/cloud-exporter.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/observability@1.8.0`. **Deprecated in `1.12.0`** in favor of [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter).
 
-> **Deprecated:** `CloudExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for new projects. Both classes share the same constructor, environment variables, and runtime behavior; `CloudExporter` keeps its original `mastra-cloud-observability-exporter` exporter `name` and `CLOUD_EXPORTER_*` error IDs so monitoring rules built against it keep working.
+> **Deprecated:** `CloudExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for new projects. Both classes share the same constructor, environment variables, and runtime behavior. `CloudExporter` keeps its original `mastra-cloud-observability-exporter` exporter `name` and `CLOUD_EXPORTER_*` error IDs so monitoring rules built against it keep working.
 
 Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.
 
@@ -183,7 +183,7 @@ The exporter batches tracing spans, logs, metrics, scores, and feedback for effi
 ### Signal Processing
 
 - `exportTracingEvent()` only exports `SPAN_ENDED` tracing events
-- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for their respective signal type
+- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for that signal type
 - All supported signal batches are uploaded to their matching Cloud publish endpoints during `flush()` and `shutdown()`
 
 ## `MastraCloudSpanRecord`

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

@@ -199,7 +199,7 @@ The probe timer doesn't keep the Node.js process alive, so short-lived and serve
 ### Signal Processing
 
 - `exportTracingEvent()` only exports `SPAN_ENDED` tracing events
-- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for their respective signal type
+- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for that signal type
 - All supported signal batches are uploaded to their matching publish endpoints during `flush()` and `shutdown()`
 
 ## Span wire format

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

@@ -2,7 +2,7 @@
 
 # OtelExporter
 
-Sends traces and logs to any OpenTelemetry-compatible observability platform. Traces use the standardized GenAI semantic conventions; logs carry their original severity and message body and are correlated to traces via both the OTEL log record's native trace context and `mastra.traceId` / `mastra.spanId` attributes.
+Sends traces and logs to any OpenTelemetry-compatible observability platform. Traces use the standardized GenAI semantic conventions. Logs carry their original severity and message body and are correlated to traces via both the OTEL log record's native trace context and `mastra.traceId` / `mastra.spanId` attributes.
 
 ## Constructor
 

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

@@ -51,7 +51,7 @@ Force flushes any pending spans to Sentry without shutting down the exporter. Wa
 async shutdown(): Promise<void>
 ```
 
-Ends all active spans, clears internal state, and closes the Sentry connection. Waits up to 2 seconds for pending data to be sent.
+Ends all active spans and clears internal state before closing the Sentry connection. Waits up to 2 seconds for pending data to be sent.
 
 ## Usage
 

package/.docs/reference/observability/tracing/processors/sensitive-data-filter.md

@@ -57,7 +57,7 @@ new SensitiveDataFilter(options?: SensitiveDataFilterOptions)
 
 **redactionToken** (`string`): Replacement value used for full redaction and short values under partial redaction. (Default: `'[REDACTED]'`)
 
-**redactionStyle** (`'full' | 'partial'`): Controls whether matched values are fully or partially redacted. (Default: `'full'`)
+**redactionStyle** (`'full' | 'partial' | 'indexed'`): Controls how matched values are redacted. (Default: `'full'`)
 
 ```typescript
 interface SensitiveDataFilterOptions {
@@ -66,7 +66,7 @@ interface SensitiveDataFilterOptions {
   redactionStyle?: RedactionStyle
 }
 
-type RedactionStyle = 'full' | 'partial'
+type RedactionStyle = 'full' | 'partial' | 'indexed'
 ```
 
 ## Redaction styles
@@ -101,6 +101,30 @@ const filter = new SensitiveDataFilter({
 { "apiKey": "sk-…789" }
 ```
 
+### Indexed redaction
+
+Indexed redaction replaces each unique value with a stable token derived from the first field name that matched it, for example `[APIKEY_1]`. The same value maps to the same token across the spans of a trace while the trace's mapping is retained, so redacted values stay correlatable without exposing the raw value. Later occurrences under other sensitive fields reuse the first token.
+
+```typescript
+const filter = new SensitiveDataFilter({
+  redactionStyle: 'indexed',
+})
+```
+
+```jsonc
+// Before (two spans in the same trace)
+[{ "apiKey": "sk-alice-key" }, { "apiKey": "sk-bob-key" }]
+
+// After
+[{ "apiKey": "[APIKEY_1]" }, { "apiKey": "[APIKEY_2]" }]
+```
+
+The mapping is scoped per trace. Numbering restarts for each trace, so tokens from different traces can't be linked.
+
+State is bounded in two ways. The filter keeps mappings for the 1000 most recently used traces. The least recently used trace is evicted beyond that, and spans arriving for an evicted trace start a fresh mapping, so later values may receive new tokens. Each trace also tracks up to 1000 unique values. Once that cap is reached, already-tracked values keep their tokens and new values are redacted with `redactionToken`.
+
+Non-string values are converted to strings before a token is assigned.
+
 ## Field matching
 
 Field names are lowercased and stripped of non-alphanumeric characters before comparison:
@@ -165,7 +189,7 @@ Returns: `AnySpan`
 
 #### `shutdown()`
 
-Completes processor shutdown. The current processor has no resources or state to clean up.
+Completes processor shutdown and clears the per-trace state used by indexed redaction.
 
 ```typescript
 await filter.shutdown()

package/.docs/reference/processors/batch-parts-processor.md

@@ -2,7 +2,7 @@
 
 # BatchPartsProcessor
 
-The `BatchPartsProcessor` is an **output processor** that batches multiple stream parts together to reduce the frequency of emissions during streaming. This processor is useful for reducing network overhead, improving user experience by consolidating small text chunks, and optimizing streaming performance by controlling when parts are emitted to the client.
+The `BatchPartsProcessor` is an **output processor** that batches multiple stream parts together to reduce the frequency of emissions during streaming. This processor is useful for reducing network overhead and consolidating small text chunks for users, while controlling emissions to optimize streaming performance.
 
 ## Usage example
 

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

@@ -40,7 +40,7 @@ const processor = new LanguageDetector({
 
 **options.includeDetectionDetails** (`boolean`): Whether to include detailed detection info in logs
 
-**options.translationQuality** (`'speed' | 'quality' | 'balanced'`): Translation quality preference: 'speed' prioritizes fast translation, 'quality' prioritizes accuracy, 'balanced' balances between speed and quality
+**options.translationQuality** (`'speed' | 'quality' | 'balanced'`): Deprecated. This option previously selected prompt-level "Quality Level" guidance, but that behavior was removed when the detection and translation prompts were streamlined. The option now has no effect. For model-specific speed and quality controls, use providerOptions when your provider supports them.
 
 **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' } })
 
@@ -74,7 +74,6 @@ export const agent = new Agent({
         'Detect language and translate non-English content to English while preserving original intent',
       minTextLength: 10,
       includeDetectionDetails: true,
-      translationQuality: 'quality',
     }),
   ],
 })

package/.docs/reference/processors/processor-interface.md

@@ -78,17 +78,17 @@ Processor methods run at different points in the agent execution lifecycle:
 └────────────────────────────────────────────────────────────────────┘
 ```
 
-| Method                | When it runs                                                                                | Use case                                                                                       |
-| --------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `processInput`        | Once at the start, before the agentic loop                                                  | Validate/transform initial user input, add context                                             |
-| `processInputStep`    | At each step of the agentic loop, before each LLM call                                      | Transform messages between steps, handle tool results                                          |
-| `processLLMRequest`   | After LLM request conversion, before the provider call                                      | Rewrite the outbound `LanguageModelV2Prompt` for the current call without persisting changes   |
-| `processAPIError`     | When an LLM API call fails                                                                  | Inspect API rejections, optionally mutate state/messages, and request a retry                  |
-| `processOutputStream` | On each streaming chunk during LLM response                                                 | Filter/modify streaming content, detect patterns in real-time                                  |
-| `processLLMResponse`  | After the LLM step completes and stream chunks are collected                                | Capture or cache the full response, run post-call side effects paired with `processLLMRequest` |
-| `processOutputStep`   | After each LLM response, before tool execution                                              | Validate output quality, implement guardrails with retry                                       |
-| `processToolResult`   | Per tool, after `tool.execute()` returns and before the result is added to the message list | Scan tool output for prompt injection, redact sensitive fields, abort on policy violations     |
-| `processOutputResult` | Once after generation completes                                                             | Post-process final response, log results                                                       |
+| Method                | When it runs                                                                                                                               | Use case                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| `processInput`        | Once at the start, before the agentic loop                                                                                                 | Validate/transform initial user input, add context                                             |
+| `processInputStep`    | At each step of the agentic loop, before each LLM call                                                                                     | Transform messages between steps, handle tool results                                          |
+| `processLLMRequest`   | After LLM request conversion, before the provider call                                                                                     | Rewrite the outbound `LanguageModelV2Prompt` for the current call without persisting changes   |
+| `processAPIError`     | When an LLM API call fails                                                                                                                 | Inspect API rejections, optionally mutate state/messages, and request a retry                  |
+| `processOutputStream` | On each streaming chunk during LLM response                                                                                                | Filter/modify streaming content, detect patterns in real-time                                  |
+| `processLLMResponse`  | After the LLM step completes and stream chunks are collected                                                                               | Capture or cache the full response, run post-call side effects paired with `processLLMRequest` |
+| `processOutputStep`   | After each LLM response, before tool execution                                                                                             | Validate output quality, implement guardrails with retry                                       |
+| `processToolResult`   | Per tool, after a locally executed tool returns or a provider-executed result arrives, before the raw result is persisted to `messageList` | Inspect tool output and enforce security policies                                              |
+| `processOutputResult` | Once after generation completes                                                                                                            | Post-process final response, log results                                                       |
 
 ## Interface definition
 
@@ -212,7 +212,7 @@ function getText(message: MastraDBMessage): string {
 
 Key points:
 
-- `message.content.parts` is the primary source. A single message can contain multiple parts, including non-text parts such as tool calls, tool results, and file parts. Filter by `part.type === 'text'` before reading `part.text`.
+- `message.content.parts` is the primary source. A single message can contain multiple parts. Non-text parts include tool calls and tool results, plus file parts. Filter by `part.type === 'text'` before reading `part.text`.
 - `message.content.content` is a flattened string kept for backward compatibility. Use it only as a fallback when `parts` is empty or missing.
 - `message.content` itself is never a plain string on `MastraDBMessage`. Legacy `CoreMessage` shapes may be strings, but processors always receive `MastraDBMessage`.
 
@@ -365,7 +365,7 @@ System messages are **reset to their original values** at the start of each step
 #### Use cases
 
 - Dynamic model switching based on step number or context
-- Disabling tools after a certain number of steps
+- Disabling tools after a configured number of steps
 - Dynamically adding or replacing tools based on conversation context
 - Transforming message part types between providers (e.g., `reasoning` → `thinking` for Anthropic)
 - Modifying messages based on step number or accumulated context
@@ -708,11 +708,11 @@ export class QualityGuardrail implements Processor {
 
 ### `processToolResult`
 
-Processes a tool's result after `tool.execute()` returns and before the result is added to the message list or fed to the next LLM call. Symmetric with `processOutputStep`, which fires before tool execution. Use this method to scan tool output for prompt injection, redact sensitive fields, or abort the run with `abort('reason', { retry: true })`.
+Processes a tool's result after a locally executed tool returns or a provider-executed result arrives, before the raw result is persisted to `messageList` or fed to the next LLM call. Symmetric with `processOutputStep`, which fires before tool execution. Use this method to enforce security policies on tool output. For example, scan for prompt injection or redact sensitive fields. Call `abort('reason', { retry: true })` to abort and retry the same step.
 
-To replace the tool's result, mutate `messageList` in place via `messageList.updateToolInvocation`. The runtime re-reads the post-processor result from the message list and overwrites the downstream tool-result stream chunk before it is enqueued, so streaming clients see the processed value.
+To replace the tool's result, mutate `messageList` in place via `messageList.updateToolInvocation`. The runtime re-reads the post-processor result from the message list and overwrites the downstream tool-result stream chunk before it's enqueued, so streaming clients see the processed value.
 
-This method does not fire when `tool.execute()` throws; it is called only for successful tool executions where a result is available.
+This method doesn't fire when `tool.execute()` throws. It's called only for successful tool executions where a result is available.
 
 ```typescript
 processToolResult?(args: ProcessToolResultArgs): ProcessorMessageResult;

package/.docs/reference/processors/stream-error-retry-processor.md

@@ -49,7 +49,7 @@ For retryable errors with a `Retry-After` response header, the processor reads c
 
 ## Retry unknown errors
 
-Set `retryUnknownErrors` to retry errors that don't match provider metadata, the built-in OpenAI matcher, or a custom matcher. Unknown-error retries use the processor-level `maxRetries` and `delayMs` values. Known authorization failures, including HTTP `401` and `403` responses, aren't retried:
+Set `retryUnknownErrors` to retry errors that don't match provider metadata or the built-in OpenAI matcher, including a custom matcher. Unknown-error retries use the processor-level `maxRetries` and `delayMs` values. Known authorization failures, including HTTP `401` and `403` responses, aren't retried:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -105,7 +105,7 @@ export const agent = new Agent({
 
 ## Default OpenAI Responses matcher
 
-`isRetryableOpenAIResponsesStreamError` matches OpenAI Responses stream error chunks with `type: 'error'` or `type: 'response.failed'`. It retries known transient OpenAI error codes and, as a fallback, errors with explicit retry guidance such as `You can retry your request`.
+`isRetryableOpenAIResponsesStreamError` matches OpenAI Responses stream error chunks with `type: 'error'` or `type: 'response.failed'`. It retries known transient OpenAI error codes. As a fallback, it retries errors with explicit retry guidance such as `You can retry your request`.
 
 `StreamErrorRetryProcessor` includes this matcher by default. You can also import it and reuse it in custom retry logic.
 

package/.docs/reference/processors/token-cost-control.md

@@ -0,0 +1,154 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# TokenCostControl
+
+The `TokenCostControl` enforces monetary cost limits across the agentic loop, blocking or warning when a configurable cost threshold is exceeded.
+
+It uses `processInputStep` to check the cost limit before each LLM call. Cost data is queried from the observability storage APIs (`getMetricAggregate`) for all scopes. For all scopes except `run`, it aggregates cost across runs within a configurable time window (defaults to 7 days). For `run` scope, it queries cost for the current trace.
+
+For token-based limits, use `TokenLimiterProcessor` instead.
+
+> **Renamed from `CostGuardProcessor`.** The `CostGuardProcessor` export (and its `CostGuard*` option and detail types) remains available as a deprecated alias for the same class, including the `'token-cost-control'` processor id. Migrate imports to `TokenCostControl`.
+
+Supports six scoping modes:
+
+- **Run scope**: Tracks cost within a single agent run via trace ID
+- **Resource scope** (default): Tracks cumulative cost per `resourceId` across runs
+- **Thread scope**: Tracks cumulative cost per `threadId` across runs
+- **User scope**: Tracks cumulative cost per `userId` across runs
+- **Organization scope**: Tracks cumulative cost per `organizationId` across runs
+- **Session scope**: Tracks cumulative cost per `sessionId` across runs
+
+> **Approximate cost control.** Cost data is persisted asynchronously via buffered exporters in the observability pipeline. Fast-running agents may exceed the configured limit before metrics are available for query. Treat `maxCost` as an approximate threshold that fast-running agents may exceed.
+
+> **Agent attribution only.** Cost is attributed via the `entityType: 'agent'` metric filter. Model calls made outside an agent run (for example, direct model usage in workflow steps) have no agent parent span and aren't counted by this guard.
+
+## Usage example
+
+Track cumulative cost per resource (default scope):
+
+```typescript
+import { TokenCostControl } from '@mastra/core/processors'
+
+const tokenCostControl = new TokenCostControl({
+  maxCost: 1.0,
+})
+```
+
+Track cumulative cost per thread with a 24-hour window and a soft warning at 80% of the limit:
+
+```typescript
+import { TokenCostControl } from '@mastra/core/processors'
+
+const tokenCostControl = new TokenCostControl({
+  maxCost: 5.0,
+  scope: 'thread',
+  window: '24h',
+  warnAtPercent: 80,
+})
+```
+
+Use a per-tier budget by passing a function as `maxCost`:
+
+```typescript
+import { TokenCostControl } from '@mastra/core/processors'
+
+const tokenCostControl = new TokenCostControl({
+  maxCost: requestContext => (requestContext?.get('tier') === 'pro' ? 10.0 : 1.0),
+  scope: 'user',
+})
+```
+
+Attach to an agent with an `onViolation` callback and a per-provider/model breakdown:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { TokenCostControl } from '@mastra/core/processors'
+
+const tokenCostControl = new TokenCostControl({
+  maxCost: 5.0,
+  scope: 'resource',
+  window: '30d',
+  strategy: 'warn',
+  includeBreakdown: true,
+})
+
+tokenCostControl.onViolation = ({ detail }) => {
+  console.log(
+    `Cost ${detail.threshold} threshold for ${detail.scopeKey}: $${detail.usage}/$${detail.limit}`,
+  )
+  for (const entry of detail.breakdown ?? []) {
+    console.log(`  ${entry.provider}/${entry.model}: $${entry.estimatedCost}`)
+  }
+}
+
+const agent = new Agent({
+  id: 'my-agent',
+  name: 'my-agent',
+  model: 'openai/gpt-5-nano',
+  inputProcessors: [tokenCostControl],
+})
+```
+
+## Constructor parameters
+
+**maxCost** (`number | ((requestContext?: RequestContext) => number)`): Maximum estimated cost allowed (e.g. 0.50 for $0.50 USD). A number must be finite and positive. A function is called with the request's RequestContext on every check, enabling per-tier or per-user budgets; if it returns anything other than a finite positive number, the check is skipped for that request (fail-open) and a warning is logged. This is an approximate limit due to metric persistence delays.
+
+**scope** (`'run' | 'resource' | 'thread' | 'user' | 'organization' | 'session'`): Scope for cost tracking. 'run' tracks cost within the current agent run via trace ID. 'resource' tracks cumulative cost per resourceId across runs (default). 'thread' tracks cumulative cost per threadId across runs. 'user', 'organization', and 'session' track cumulative cost per userId, organizationId, and sessionId respectively, read from the plain RequestContext keys 'userId', 'organizationId', and 'sessionId'. All scopes require observability storage with getMetricAggregate support. (Default: `'resource'`)
+
+**window** (`'1h' | '6h' | '24h' | '7d' | '30d' | '365d'`): Time window for cost aggregation for all scopes except 'run'. (Default: `'7d'`)
+
+**strategy** (`'block' | 'warn'`): Strategy when the cost limit is exceeded. 'block' aborts with a TripWire error. 'warn' logs a warning and calls onViolation at most once per request, then allows the step to proceed. (Default: `'block'`)
+
+**message** (`string`): Custom message template for the abort reason. Supports {usage} and {limit} placeholders. (Default: `'Cost control: estimated cost limit exceeded ({usage}/{limit})'`)
+
+**warnAtPercent** (`number`): Optional soft threshold as a percentage of maxCost (exclusive 0-100, e.g. 80). When the estimated cost reaches this percentage of the limit but is still below it, a warning is logged and onViolation is called once per request with threshold: "soft", regardless of strategy. Never aborts the step.
+
+**includeBreakdown** (`boolean`): When true, violations (soft and hard) include a per-provider/model cost breakdown queried via getMetricBreakdown. The breakdown is capped at the top 10 provider/model groups ranked by aggregated token volume, not by spend. The breakdown query runs only when a violation trips, never on the happy path. If the configured store does not support breakdown queries or the query fails, the violation fires without the breakdown field. (Default: `false`)
+
+## Instance properties
+
+**id** (`'token-cost-control'`): Processor identifier.
+
+**name** (`'Token Cost Control'`): Processor display name.
+
+**onViolation** (`(violation: ProcessorViolation) => void | Promise<void>`): Callback invoked when a cost violation is detected, regardless of strategy. For the warn strategy and for soft thresholds, the guard calls it with a TokenCostControlViolationDetail (usage, limit, threshold, and optional breakdown) at most once per request per threshold level. Errors thrown by the callback on this path are caught and logged through the Mastra logger. For the block strategy, the processor runner invokes it with the TripWire metadata as the detail (see Error behavior) and silently catches callback errors. Use for side effects like alerting, logging to external systems, or emailing users.
+
+**processInputStep** (`(args: ProcessInputStepArgs) => Promise<void>`): Checks cumulative estimated cost against the resolved maxCost before each LLM call. Queries observability storage for cost data: run scope filters by trace ID, all other scopes filter by their respective IDs with a time window. Calls abort() when the limit is exceeded (block strategy) or logs a warning (warn strategy). Cost checks are approximate due to metric persistence delays.
+
+## Error behavior
+
+When the `block` strategy is active (default), `TokenCostControl` calls `abort()` with `retry: false` when the cost limit is exceeded. The TripWire metadata includes:
+
+- `processorId`: `'token-cost-control'`
+- `usage`: Current cumulative usage (`estimatedCost`, `costUnit`)
+- `maxCost`: The resolved cost limit for the request
+- `scope`: The active scope
+- `scopeKey`: The scope identifier for non-run scopes (if applicable)
+- `threshold`: Always `'hard'`, since only the hard limit aborts
+- `breakdown`: Per-provider/model cost entries (only when `includeBreakdown` is enabled and the breakdown query succeeds)
+
+With the `warn` strategy, the hard-limit warning and `onViolation` callback fire at most once per request. Subsequent steps in the same request proceed without repeating the warning.
+
+Numbers interpolated into violation messages are normalized to at most 6 decimal places, so messages never contain float precision artifacts.
+
+## Scoping behavior
+
+| Scope          | Tracks across runs | Filter                         | Requires context                         |
+| -------------- | ------------------ | ------------------------------ | ---------------------------------------- |
+| `run`          | No                 | `traceId` from current span    | Tracing context (automatic)              |
+| `resource`     | Yes                | `resourceId` + time window     | `resourceId` in `RequestContext`         |
+| `thread`       | Yes                | `threadId` + time window       | `threadId` in `RequestContext`           |
+| `user`         | Yes                | `userId` + time window         | `userId` key in `RequestContext`         |
+| `organization` | Yes                | `organizationId` + time window | `organizationId` key in `RequestContext` |
+| `session`      | Yes                | `sessionId` + time window      | `sessionId` key in `RequestContext`      |
+
+All scopes require observability storage with `getMetricAggregate` support. If the Mastra instance doesn't have observability storage configured, an error is thrown at registration time.
+
+For `run` scope, the processor reads the trace ID from the current span's tracing context. If no tracing context is available, the check is skipped (fail-open).
+
+For all other scopes, if the required context ID is missing at runtime, the check is skipped. Observability query failures are handled with a fail-open strategy: if a query fails, a warning is logged through the Mastra logger and the step proceeds.
+
+> **The `user`, `organization`, and `session` scopes require annotated traces.** These scopes match metric records by their `userId`, `organizationId`, and `sessionId` fields, which are populated from span metadata on the trace (for example, via tracing options metadata). If your traces don't carry the matching metadata, these scopes match zero records and the guard never trips. Setting the RequestContext key alone isn't enough: both the RequestContext key (for scope resolution) and the span metadata (for cost attribution) must be present.
+
+> **Note on metric persistence delay.** The observability pipeline uses buffered exporters that flush metrics asynchronously. A short delay exists between when an LLM call completes and when its cost metrics are available for query. During high-frequency agent execution, the cost control may not detect a limit breach until one or more steps after the actual cost exceeded the threshold.

package/.docs/reference/rag/chunking-and-embedding.md

@@ -127,7 +127,7 @@ const { embeddings } = await embedMany({
 })
 ```
 
-> **Vector Database Compatibility:** When storing embeddings, the vector database index must be configured to match the output size of your embedding model. If the dimensions don't match, you may get errors or data corruption.
+> **Vector Database Compatibility:** When storing embeddings, configure the vector database index to match the output size of your embedding model to avoid errors or data corruption from mismatched dimensions.
 
 ## Example: Complete pipeline
 

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

@@ -201,7 +201,7 @@ const results = await store.query({
 ### Amazon S3 Vectors
 
 - Equality values must be primitives (string/number/boolean). `null`/`undefined`, arrays, objects, and Date aren't allowed for equality. Range operators accept numbers or Date (Dates are normalized to epoch ms).
-- `$in`/`$nin` require **non-empty arrays of primitives**; Date elements are allowed and normalized to epoch ms. **Array equality** isn't supported.
+- `$in`/`$nin` require **non-empty arrays of primitives**. Date elements are allowed and normalized to epoch ms. **Array equality** isn't supported.
 - Implicit AND is canonicalized (`{a:1,b:2}` → `{$and:[{a:1},{b:2}]`). Logical operators must contain field conditions and use non-empty arrays. They may appear only at the root or within other logical operators (not inside field values).
 - Keys listed in `nonFilterableMetadataKeys` at index creation are stored but not filterable. This setting is immutable.
 - $exists requires a boolean value.

package/.docs/reference/server/koa-adapter.md

@@ -76,7 +76,7 @@ app.listen(3000, () => {
 
 ## Error handling
 
-The Koa adapter propagates errors from route handlers up through Koa's middleware chain, following Koa's standard error handling pattern. This means you can use regular Koa error-handling middleware:
+The Koa adapter propagates errors from route handlers up through Koa's middleware chain, following Koa's standard error handling pattern. You can use regular Koa error-handling middleware:
 
 ```typescript
 const app = new Koa()

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

@@ -100,7 +100,7 @@ Returns: `boolean`
 
 #### `handleWebhook(request)`
 
-Process an incoming webhook request. Extracts the resource ID from the payload, finds matching subscriptions, builds a notification for each, and calls `notify()`.
+Process an incoming webhook request. Extracts the resource ID from the payload and finds matching subscriptions. It builds a notification for each subscription and calls `notify()`.
 
 ```typescript
 const result = await webhookProvider.handleWebhook({

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

@@ -234,7 +234,7 @@ const storage = new MongoDBStore({
 
 `prune()` deletes rows but doesn't shrink the database file. On SQLite/libSQL the freed pages go on a freelist and are reused by future writes, so the file stops growing: for most users this alone solves the unbounded-growth problem.
 
-Handing that free space back to the OS is a separate concern that Mastra doesn't manage. If you specifically need to shrink the file, run the underlying database's compaction (for example `VACUUM` on self-hosted libSQL) yourself in a maintenance window. A full `VACUUM` locks the file and needs roughly twice the file size in free disk. On PostgreSQL, autovacuum reclaims dead tuples for reuse automatically; a manual `VACUUM FULL` is only needed if you must return disk to the OS.
+Handing that free space back to the OS is a separate concern that Mastra doesn't manage. If you specifically need to shrink the file, run the underlying database's compaction (for example `VACUUM` on self-hosted libSQL) yourself in a maintenance window. A full `VACUUM` locks the file and needs roughly twice the file size in free disk. On PostgreSQL, autovacuum reclaims dead tuples for reuse automatically. A manual `VACUUM FULL` is only needed if you must return disk to the OS.
 
 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.
 

package/.docs/reference/tools/bedrock-kb-tool.md

@@ -65,7 +65,7 @@ The tool returns an object with:
 | ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | `content`  | `string`                  | The text content of the retrieved passage.                                                                                            |
 | `source`   | `string \| undefined`     | The source URI when Bedrock provides one. Agentic retrieval only includes this field when the result metadata contains `_source_uri`. |
-| `score`    | `number \| undefined`     | The relevance score returned by standard retrieval. The agentic API doesn't return a score for result items.                          |
+| `score`    | `number \| undefined`     | The relevance score returned by standard retrieval, which the agentic API omits from result items.                                    |
 | `metadata` | `Record<string, unknown>` | Additional metadata from the retrieval result.                                                                                        |
 
 ## Retrieval Modes

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

@@ -2,7 +2,7 @@
 
 # MCPClient
 
-The `MCPClient` class provides a way to manage multiple MCP server connections and their tools in a Mastra application. It handles connection lifecycle, tool namespacing, and provides access to tools across all configured servers.
+The `MCPClient` class provides a way to manage multiple MCP server connections and their tools in a Mastra application. It handles connection lifecycle and tool namespacing while providing access to tools across all configured servers.
 
 ## Constructor
 
@@ -248,7 +248,7 @@ const res = await agent.stream(prompt, {
 
 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.
+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 or a database, as well as 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()
@@ -991,7 +991,7 @@ try {
 
 Concurrent `authenticate()` calls for the same server join the pending flow. Different servers authenticate independently. With valid stored tokens the call reconnects without opening a browser.
 
-Hosts that drive the flow themselves can capture the authorization code with the exported `createOAuthCallbackServer` helper, which binds a one-shot loopback server, validates the OAuth `state` parameter, and resolves with the code. It creates a plain HTTP server, so it's only for local loopback redirects. Web applications that use an HTTPS redirect URL must host their own callback endpoint and drive the provider directly rather than using this helper:
+Hosts that drive the flow themselves can capture the authorization code with the exported `createOAuthCallbackServer` helper, which binds a one-shot loopback server and validates the OAuth `state` parameter before resolving with the code. It creates a plain HTTP server, so it's only for local loopback redirects. Web applications that use an HTTPS redirect URL must host their own callback endpoint and drive the provider directly rather than using this helper:
 
 ```typescript
 import { createOAuthCallbackServer, getCallbackUrlCandidates } from '@mastra/mcp'

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

@@ -2,7 +2,7 @@
 
 # MCPServer
 
-The `MCPServer` class provides the functionality to expose your existing Mastra tools and Agents as a Model Context Protocol (MCP) server. This allows any MCP client (like Cursor, Windsurf, or Claude Desktop) to connect to these capabilities and make them available to an agent.
+The `MCPServer` class provides the functionality to expose your existing Mastra tools and Agents as a Model Context Protocol (MCP) server. Any MCP client, such as Cursor, Windsurf, or Claude Desktop, can connect to these capabilities and make them available to an agent.
 
 Note that if you only need to use your tools or agents directly within your Mastra application, you don't necessarily need to create an MCP server. This API is specifically for exposing your Mastra tools and agents to _external_ MCP clients.
 
@@ -95,7 +95,7 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
 
 A powerful feature of `MCPServer` is its ability to automatically expose your Mastra Agents as callable tools. When you provide agents in the `agents` property of the configuration:
 
-- **Tool Naming**: Each agent is converted into a tool named `ask_<agentKey>`, where `<agentKey>` is the key you used for that agent in the `agents` object. For instance, if you configure `agents: { myAgentKey: myAgentInstance }`, a tool named `ask_myAgentKey` will be created.
+- **Tool Naming**: Each agent is converted into a tool with the name `ask_<agentKey>`, where `<agentKey>` is the key you used for that agent in the `agents` object. For instance, if you configure `agents: { myAgentKey: myAgentInstance }`, a tool with the name `ask_myAgentKey` will be created.
 
 - **Tool Functionality**:
 
@@ -104,7 +104,7 @@ A powerful feature of `MCPServer` is its ability to automatically expose your Ma
   - **Execution**: When this tool is called, it invokes the corresponding agent's `generate()` method with the provided `query`.
   - **Output**: The direct result from the agent's `generate()` method is returned as the output of the tool.
 
-- **Name collisions.** If an explicit tool defined in the `tools` configuration has the same name as an agent-derived tool (e.g., a tool named `ask_myAgentKey` alongside an agent keyed as `myAgentKey`), the _explicitly defined tool will take precedence_. The agent won't be converted into a tool in this conflicting case, and a warning will be logged.
+- **Name collisions.** If an explicit tool defined in the `tools` configuration has the same name as an agent-derived tool (e.g., a tool with the name `ask_myAgentKey` alongside an agent keyed as `myAgentKey`), the _explicitly defined tool will take precedence_. The agent won't be converted into a tool in this conflicting case, and a warning will be logged.
 
 This makes it straightforward to allow MCP clients to interact with your agents using natural language queries, like any other tool.
 
@@ -116,7 +116,7 @@ The description for this generated tool will be: "Ask agent `<agent.name>` a que
 
 For an agent to be converted into a tool, it **must** have a non-empty `description` string property set in its configuration when it was instantiated (e.g., `new Agent({ id: 'my-agent', name: 'myAgent', description: 'This agent does X.', ... })`). If an agent is passed to `MCPServer` with a missing or empty `description`, an error will be thrown when the `MCPServer` is instantiated, and server setup will fail.
 
-This allows you to quickly expose the generative capabilities of your agents through the MCP, enabling clients to "ask" your agents questions directly.
+Clients can use MCP to access your agents' generative capabilities and ask them questions directly.
 
 ### Accessing MCP Context in Tools
 
@@ -1240,7 +1240,7 @@ const customMiddleware = createOAuthMiddleware({
 
 ## Authentication context
 
-Tools can access request metadata via `context.mcp.extra` when using HTTP-based transports. This allows you to pass authentication info, user context, or any custom data from your HTTP middleware to your MCP tools.
+Tools can access request metadata via `context.mcp.extra` when using HTTP-based transports. You can pass authentication info and user context, as well as custom data from your HTTP middleware to your MCP tools.
 
 ### How it works