@mastra/mcp-docs-server 1.2.27-alpha.1 → 1.2.27-alpha.13

package/.docs/reference/agents/generate.md

@@ -108,7 +108,7 @@ const result = await agent.generate('message for agent')
 
 **options.structuredOutput.fallbackValue** (`<S extends ZodTypeAny>`): Fallback value to use when schema validation fails and errorStrategy is 'fallback'.
 
-**options.structuredOutput.instructions** (`string`): Additional instructions for the structured output model.
+**options.structuredOutput.instructions** (`string`): Additional instructions for the structured output model. With jsonPromptInjection and no structuring model, this text is injected into the prompt in place of the serialized schema.
 
 **options.structuredOutput.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): Controls how the JSON schema reaches the model. Set to 'auto' to use native structured output when supported and inline prompt injection otherwise.
 

package/.docs/reference/auth/clerk.md

@@ -23,6 +23,26 @@ export const mastra = new Mastra({
 })
 ```
 
+## Restricting login to a single organization
+
+Set `organizationId` or `organizationSlug` to only allow members of a specific Clerk organization to sign in. Non-members are rejected during authorization. Configure only one of the two. Setting both throws at startup, so login can't be granted to two different organizations.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthClerk } from '@mastra/auth-clerk'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthClerk({
+      jwksUri: process.env.CLERK_JWKS_URI,
+      publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+      secretKey: process.env.CLERK_SECRET_KEY,
+      organizationId: process.env.CLERK_ORGANIZATION_ID,
+    }),
+  },
+})
+```
+
 ## Constructor parameters
 
 **publishableKey** (`string`): Your Clerk publishable key. Can be found in your Clerk Dashboard under API Keys. (Default: `process.env.CLERK_PUBLISHABLE_KEY`)
@@ -31,9 +51,13 @@ export const mastra = new Mastra({
 
 **jwksUri** (`string`): The JWKS URI from your Clerk application. Used to verify JWT signatures. (Default: `process.env.CLERK_JWKS_URI`)
 
+**organizationId** (`string`): Restrict login to members of a single Clerk organization, identified by its ID. Users who are not members of this organization are denied access. (Default: `process.env.CLERK_ORGANIZATION_ID`)
+
+**organizationSlug** (`string`): Restrict login to members of a single Clerk organization, identified by its slug. Users who are not members of this organization are denied access. (Default: `process.env.CLERK_ORGANIZATION_SLUG`)
+
 **name** (`string`): Custom name for the auth provider instance.
 
-**authorizeUser** (`(user: User, request: HonoRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users.
+**authorizeUser** (`(user: User, request: HonoRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users, unless organizationId or organizationSlug is set, in which case only members of that organization are allowed.
 
 ## Related
 

package/.docs/reference/cli/mastra.md

@@ -1079,6 +1079,90 @@ See the [Storage migration guide](https://mastra.ai/reference/migrations/upgrade
 
 It accepts [common flags](#common-flags).
 
+## `mastra traces import`
+
+Imports historical traces from a supported observability provider into an existing Mastra Platform project. The command prepares complete traces locally, uploads whole-trace batches, supports resume, and verifies a sample through Mastra Platform.
+
+```bash
+mastra traces import <provider> [options]
+```
+
+The following provider is currently supported:
+
+| Provider | Argument   | Requirements                                       |
+| -------- | ---------- | -------------------------------------------------- |
+| Langfuse | `langfuse` | Langfuse Cloud or self-hosted Langfuse v4 or later |
+
+See [Import existing traces](https://mastra.ai/docs/mastra-platform/observability) for the complete workflow, data mapping, local-file lifecycle, and limits.
+
+### Options
+
+#### `--project <name|slug|id>`
+
+Selects the destination Mastra Platform project. `MASTRA_PROJECT_ID` takes precedence when set. Without either value, the command uses the project linked in `.mastra-project.json`.
+
+#### `--from <date>`
+
+Sets the inclusive start of the import window as an ISO 8601 date or timestamp. It defaults to 30 days before `--to`, clamped to the current 30-day Platform retention boundary.
+
+#### `--to <date>`
+
+Sets the exclusive end of the import window as an ISO 8601 date or timestamp. It defaults to the time when the import starts and can't be in the future.
+
+The complete window must fall within the current 30-day Platform retention period, `--from` must be earlier than `--to`, and the window can't exceed 30 days.
+
+#### `--dry-run`
+
+Reads the source and prepares valid traces locally without uploading them. The command writes a report and prints a command that resumes the prepared import.
+
+#### `--resume <import-id>`
+
+Resumes a prepared import using its saved provider, destination project, date window, and acknowledged progress. Use the same destination project shown in the generated resume command. This option can't be combined with `--from`, `--to`, or `--dry-run`.
+
+#### `-y, --yes`
+
+Uploads without asking for confirmation.
+
+### Environment variables
+
+The command loads `.env` and `.env.local` from the current directory.
+
+| Variable                       | Required                                        | Description                                                                                                       |
+| ------------------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `LANGFUSE_PUBLIC_KEY`          | For new Langfuse imports                        | Public project API key.                                                                                           |
+| `LANGFUSE_SECRET_KEY`          | For new Langfuse imports                        | Secret project API key.                                                                                           |
+| `LANGFUSE_BASE_URL`            | No                                              | Langfuse host. Defaults to `https://cloud.langfuse.com`.                                                          |
+| `MASTRA_API_TOKEN`             | For headless authentication                     | Mastra Platform API token. Without it, the command uses credentials from `mastra auth login`.                     |
+| `MASTRA_ORG_ID`                | With `MASTRA_API_TOKEN`                         | Organization that owns the destination project.                                                                   |
+| `MASTRA_PLATFORM_ACCESS_TOKEN` | For upload and read-back with interactive login | Mastra Platform access token for the destination. Not required for `--dry-run` or when `MASTRA_API_TOKEN` is set. |
+| `MASTRA_PROJECT_ID`            | When no project is otherwise linked             | Destination project ID. Takes precedence over `--project`.                                                        |
+
+### Examples
+
+Preview the default 30-day window without uploading:
+
+```bash
+mastra traces import langfuse --project my-project --dry-run
+```
+
+Import a smaller date window without a confirmation prompt:
+
+```bash
+mastra traces import langfuse \
+  --project my-project \
+  --from "$FROM" \
+  --to "$TO" \
+  --yes
+```
+
+Resume an existing import:
+
+```bash
+mastra traces import langfuse \
+  --resume 00000000-0000-0000-0000-000000000000 \
+  --project my-project
+```
+
 ## `mastra api`
 
 Calls a Mastra runtime server with JSON input and JSON output. Use it for local development servers, deployed Mastra platform projects, self-hosted Mastra servers, or hosted Mastra Platform Observability APIs.
@@ -1617,7 +1701,7 @@ mastra api metric label-values '{"metricName":"latency_ms","labelKey":"model","p
 
 #### Observability with `curl`
 
-You can call the hosted observability API directly with your platform access token and project ID. The examples below use the United States host. Substitute `https://observability.eu.mastra.ai` for a European Union environment. The [hosted feedback query API](https://mastra.ai/docs/mastra-platform/api) documents feedback endpoints that don't have CLI commands:
+You can call the hosted observability API directly with your platform access token and project ID. The examples below use the United States host. Substitute `https://observability.eu.mastra.ai` for a European Union environment. The [Feedback API](https://mastra.ai/docs/mastra-platform/api) documents feedback endpoints that don't have CLI commands:
 
 ```bash
 curl -sS "https://observability.mastra.ai/api/observability/traces?page=0&perPage=20" \

package/.docs/reference/client-js/agent-controller.md

@@ -219,31 +219,92 @@ Returns: `Promise<SendNotificationResult>`
 
 `onEvent` receives every event the session emits, discriminated by `event.type`:
 
-| Group        | Events                                                                                                                                                                                                                                                                                  |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Run          | `agent_start`, `agent_end`, `usage_update`, `goal_evaluation`, `follow_up_queued`                                                                                                                                                                                                       |
-| Messages     | `message_start`, `message_update`, `message_end`                                                                                                                                                                                                                                        |
-| Tools        | `tool_input_start`, `tool_input_delta`, `tool_input_end`, `tool_start`, `tool_update`, `tool_end`, `shell_output`, `command_exit`, `tool_approval_required`, `tool_suspended`, `tool_suspension_cancelled`, `task_updated`                                                              |
-| Session      | `state_changed`, `display_state_changed`, `mode_changed`, `model_changed`, `thread_changed`, `thread_created`, `thread_deleted`, `thread_title_updated`                                                                                                                                 |
-| Subagents    | `subagent_start`, `subagent_text_delta`, `subagent_tool_start`, `subagent_tool_end`, `subagent_end`, `subagent_model_changed`                                                                                                                                                           |
-| Memory       | `om_observation_start`, `om_observation_end`, `om_observation_failed`, `om_reflection_start`, `om_reflection_end`, `om_reflection_failed`, `om_buffering_start`, `om_buffering_end`, `om_buffering_failed`, `om_model_changed`, `om_activation`, `om_status`, `om_thread_title_updated` |
-| Workspace    | `workspace_ready`, `workspace_error`, `workspace_status_changed`                                                                                                                                                                                                                        |
-| Notification | `notification`, `notification_summary`, `info`, `error`                                                                                                                                                                                                                                 |
+| Group       | Events                                                                                                                                                                                                                                                                                  |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Run         | `agent_start`, `agent_end`, `usage_update`, `goal_evaluation`, `follow_up_queued`                                                                                                                                                                                                       |
+| Messages    | `message_start`, `message_update`, `message_end`                                                                                                                                                                                                                                        |
+| Tools       | `tool_input_start`, `tool_input_delta`, `tool_input_end`, `tool_start`, `tool_update`, `tool_end`, `shell_output`, `command_exit`, `tool_approval_required`, `tool_suspended`, `tool_suspension_cancelled`, `task_updated`                                                              |
+| Session     | `state_changed`, `display_state_changed`, `mode_changed`, `model_changed`, `thread_changed`, `thread_created`, `thread_deleted`, `thread_title_updated`                                                                                                                                 |
+| Subagents   | `subagent_start`, `subagent_text_delta`, `subagent_tool_start`, `subagent_tool_end`, `subagent_end`, `subagent_model_changed`                                                                                                                                                           |
+| Memory      | `om_observation_start`, `om_observation_end`, `om_observation_failed`, `om_reflection_start`, `om_reflection_end`, `om_reflection_failed`, `om_buffering_start`, `om_buffering_end`, `om_buffering_failed`, `om_model_changed`, `om_activation`, `om_status`, `om_thread_title_updated` |
+| Workspace   | `workspace_ready`, `workspace_error`, `workspace_status_changed`                                                                                                                                                                                                                        |
+| Diagnostics | `info`, `error`                                                                                                                                                                                                                                                                         |
 
-`message_*` events carry a `MastraDBMessage` and `thread_created` carries a thread, with timestamps hydrated to `Date`.
+Notifications are delivered as agent signals carried on messages rather than as `notification` or `notification_summary` controller events.
 
-A controller can also emit events the SDK doesn't type. `AgentControllerEvent` is the union of `KnownAgentControllerEvent` and `OtherAgentControllerEvent`. Because `OtherAgentControllerEvent.type` is `string`, comparing `event.type` to a literal doesn't narrow the union. Narrow with `isKnownAgentControllerEvent(event)` first:
+A message lifecycle uses three event shapes:
+
+- `message_start` carries the initial `MastraDBMessage`, with `createdAt` hydrated to `Date`.
+- `message_update` carries the message `id` and a compact text, reasoning, or part update.
+- `message_end` carries the `id` of the completed message.
+
+`thread_created` also carries a thread with timestamps hydrated to `Date`.
+
+A controller can emit events the SDK doesn't type. `AgentControllerEvent` is the union of `KnownAgentControllerEvent` and `OtherAgentControllerEvent`. Because `OtherAgentControllerEvent.type` is `string`, comparing `event.type` to a literal doesn't narrow the union. Narrow with `isKnownAgentControllerEvent(event)` first, then reconstruct messages by ID:
 
 ```typescript
-import { isKnownAgentControllerEvent } from '@mastra/client-js'
+import {
+  isKnownAgentControllerEvent,
+  type AgentControllerEvent,
+  type KnownAgentControllerEvent,
+  type MastraDBMessage,
+} from '@mastra/client-js'
+
+type MessageUpdate = Extract<KnownAgentControllerEvent, { type: 'message_update' }>['event']
+
+const activeMessages = new Map<string, MastraDBMessage>()
+
+function applyUpdate(message: MastraDBMessage, update: MessageUpdate): MastraDBMessage {
+  const parts = [...message.content.parts]
+
+  if (update.type === 'text-delta') {
+    const index = parts.findLastIndex(part => part.type === 'text')
+    const part = parts[index]
+
+    if (part?.type === 'text') {
+      parts[index] = { ...part, text: part.text + update.delta }
+    } else {
+      parts.push({ type: 'text', text: update.delta })
+    }
+  } else if (update.type === 'reasoning-delta') {
+    const part = parts[update.index]
+    const reasoning = part?.type === 'reasoning' ? part.reasoning + update.delta : update.delta
+    parts[update.index] = {
+      ...(part?.type === 'reasoning' ? part : { type: 'reasoning' as const }),
+      reasoning,
+      details: [{ type: 'text', text: reasoning }],
+    }
+  } else {
+    parts[update.index] = update.part
+  }
+
+  return { ...message, content: { ...message.content, parts } }
+}
 
 function handleEvent(event: AgentControllerEvent) {
   if (!isKnownAgentControllerEvent(event)) return
 
   switch (event.type) {
-    case 'message_update':
-      render(event.message)
+    case 'message_start':
+      activeMessages.set(event.message.id, structuredClone(event.message))
+      break
+    case 'message_update': {
+      const message = activeMessages.get(event.id)
+      if (!message) break
+
+      const updated = applyUpdate(message, event.event)
+      activeMessages.set(event.id, updated)
+      render(updated)
+      break
+    }
+    case 'message_end': {
+      const message = activeMessages.get(event.id)
+      if (!message) break
+
+      renderComplete(message)
+      activeMessages.delete(event.id)
       break
+    }
     case 'tool_approval_required':
       showApproval(event.toolCallId)
       break
@@ -251,7 +312,7 @@ function handleEvent(event: AgentControllerEvent) {
 }
 ```
 
-Use `agentControllerMessageText(message)` to pull the plain text out of a message's nested content parts.
+Use `agentControllerMessageText(message)` to pull the plain text out of a reconstructed message's nested content parts.
 
 ## Related
 

package/.docs/reference/client-js/agents.md

@@ -119,6 +119,31 @@ while (true) {
 }
 ```
 
+#### Cancelling a stream
+
+Cancelling the response body aborts the underlying HTTP request and stops any pending client tool executions and follow-up requests:
+
+```typescript
+const response = await agent.stream('Tell me a story')
+const reader = response.body.getReader()
+
+const { value } = await reader.read()
+await reader.cancel('user navigated away')
+```
+
+You can also pass an `abortSignal` to cancel from outside the stream. The same option is available on `streamUntilIdle()`, `resumeStream()`, `resumeStreamUntilIdle()`, `approveToolCall()`, `declineToolCall()`, `generate()`, and `generateLegacy()`:
+
+```typescript
+const controller = new AbortController()
+
+const response = await agent.stream('Tell me a story', {
+  abortSignal: controller.signal,
+})
+
+// Later
+controller.abort()
+```
+
 #### AI SDK compatible format
 
 To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkStream`:

package/.docs/reference/client-js/mastra-client.md

@@ -81,7 +81,7 @@ You can also pass `requestContext` as a `Record<string, any>`.
 
 **getWorkflow(workflowId)** (`Workflow`): Retrieves a specific workflow instance by ID.
 
-**getAgentBuilderActions()** (`Promise<Record<string, WorkflowInfo>>`): Returns all available Agent Builder actions. See Agent Builder API.
+**getAgentBuilderActions()** (`Promise<GetAgentBuilderActionsResponse>`): Returns all available Agent Builder actions. See Agent Builder API.
 
 **getAgentBuilderAction(actionId)** (`AgentBuilder`): Retrieves an Agent Builder action by ID. See Agent Builder API.
 

package/.docs/reference/client-js/observability.md

@@ -65,9 +65,9 @@ const selected = await mastraClient.getTrace(list.spans[0].traceId)
 
 It accepts the same filtering, ordering and delta-polling arguments as `listTraces()`. Use `listTraces()` when you actually need the full span payloads.
 
-## Querying traces with recursive predicates
+## Querying traces and threads
 
-`queryTraces()` finds completed logical traces using trace fields and conditions over related spans or scores. Every query requires an ISO timestamp range of at most 31 days.
+`queryTraces()` finds completed logical traces using trace fields and conditions over related spans, scores, or feedback. Every query requires an ISO timestamp range of at most 31 days.
 
 ```typescript
 const result = await mastraClient.queryTraces({
@@ -89,9 +89,106 @@ const result = await mastraClient.queryTraces({
 })
 ```
 
-The API limits predicate depth, nodes, related clauses, set members, literal bytes, and the total literal budget before storage execution. Cursor pages are deterministic but aren't a database snapshot, so signals written between requests can change later pages. PostgreSQL and ClickHouse queries have a configurable 15-second execution timeout.
+### Discover trace-query fields and values
 
-See [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for the complete limits, request fields, predicates, grouping, cursor pagination, response shapes, and errors.
+`getTraceQueryFields()` returns canonical query fields and observed top-level string metadata fields for one predicate scope. The response includes each field's value kind, supported operators, and whether value suggestions are available.
+
+```typescript
+const timeRange = {
+  from: '2026-08-01T00:00:00.000Z',
+  to: '2026-08-08T00:00:00.000Z',
+}
+
+const fields = await mastraClient.getTraceQueryFields({
+  timeRange,
+  predicateScope: 'spans',
+  search: 'model',
+  limit: 25,
+})
+```
+
+Use the exact local path from the response with the same scope. For example, `model` belongs inside a `spans.some` or `spans.none` predicate. A global picker can fetch `trace`, `spans`, `scores`, and `feedback` in parallel.
+
+Call `getTraceQueryValues()` only after selecting a field with `valueSuggestions: true`:
+
+```typescript
+const controller = new AbortController()
+
+const values = await mastraClient.getTraceQueryValues(
+  {
+    timeRange,
+    predicateScope: 'spans',
+    path: 'model',
+    search: 'claude',
+    limit: 25,
+  },
+  { signal: controller.signal },
+)
+
+// Cancel this autocomplete request when the search text changes.
+controller.abort()
+```
+
+Both methods use case-insensitive literal substring search and accept an empty search. Limits default to 25 and can't exceed 100. Results are ordered by occurrence count, then deterministically by path or value. `observedFieldsTruncated` and `valuesTruncated` indicate that the caller should refine `search`. Discovery has no cursor.
+
+Suggestions are bounded and advisory. Manual values remain valid when suggestions are unavailable, empty, or truncated. Discovery doesn't accept a draft query predicate. The client doesn't retry either request, and a per-call `AbortSignal` takes precedence over the signal configured on `MastraClient`.
+
+A discovery timeout rejects with `504 TRACE_QUERY_EXECUTION_TIMEOUT`. Backend memory or resource exhaustion rejects with `503 TRACE_QUERY_RESOURCE_LIMIT`. Neither error contains partial suggestions; truncation flags are only present on successful, completely ranked responses.
+
+`queryTraceThreads()` returns thread identities derived from observability traces after applying eligibility and cross-trace conditions. It doesn't read or return memory thread records or messages. In this example, one production trace can have the low factuality score while another production trace in the same thread has the clinician correction:
+
+```typescript
+const result = await mastraClient.queryTraceThreads({
+  traces: {
+    timeRange: {
+      from: '2026-08-01T00:00:00.000Z',
+      to: '2026-08-08T00:00:00.000Z',
+    },
+    where: {
+      op: 'eq',
+      left: { path: 'environment' },
+      right: { literal: 'production' },
+    },
+  },
+  where: {
+    op: 'and',
+    args: [
+      {
+        traces: {
+          some: {
+            scores: {
+              some: {
+                op: 'lt',
+                left: { path: 'score' },
+                right: { literal: 0.6 },
+              },
+            },
+          },
+        },
+      },
+      {
+        traces: {
+          some: {
+            feedback: {
+              some: {
+                op: 'eq',
+                left: { path: 'feedbackType' },
+                right: { literal: 'clinician-correction' },
+              },
+            },
+          },
+        },
+      },
+    ],
+  },
+})
+
+// { threads: [{ threadId: 'thread-123' }], page: { next: null } }
+```
+
+The API limits predicate depth, nodes, related clauses, set members, literal bytes, and the total literal budget before storage execution. Cursor pages are deterministic but aren't a database snapshot, so signals written between requests can change later pages. PostgreSQL and ClickHouse trace and thread queries have a configurable 15-second execution timeout.
+
+See [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for the complete limits, request fields, predicates, thread qualification semantics, cursor pagination, response shapes, and errors.
 
 ## Deleting traces
 
@@ -136,7 +233,7 @@ const scores = await mastraClient.listScoresBySpan({
 
 ## Feedback
 
-Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections through the target Mastra runtime and its configured observability storage. They don't call the hosted Mastra Platform feedback query API. See the [feedback guide](https://mastra.ai/docs/observability/feedback) for examples and the [feedback reference](https://mastra.ai/reference/observability/feedback) for full schemas.
+Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections through the target Mastra runtime and its configured observability storage. They don't call the hosted Mastra Platform Feedback API. See the [feedback guide](https://mastra.ai/docs/observability/feedback) for examples and the [feedback reference](https://mastra.ai/reference/observability/feedback) for full schemas.
 
 ### Creating feedback
 
@@ -188,6 +285,8 @@ const feedback = await mastraClient.listFeedback({
 })
 ```
 
+`filters` accepts every [`FeedbackFilter`](https://mastra.ai/reference/observability/feedback) field. The client sends them as query parameters on `GET /api/observability/feedback`. See [list query parameters](https://mastra.ai/reference/observability/feedback).
+
 ### Aggregating feedback
 
 Aggregate numeric feedback values, such as ratings or thumbs encoded as `1` and `-1`:

package/.docs/reference/code-sdk/mount-agent-controller.md

@@ -94,6 +94,29 @@ const { controller } = await mountAgentControllerOnMastra({ mastra })
 
 **authStorage** (`AuthStorage`): Credential storage used by the built-in model gateway.
 
+## Nested controllers in plugins
+
+A plugin that boots another controller in the same process must borrow the host's storage instead of opening the same database files with its own native SQLite library.
+
+### `context.getStorage()`
+
+The optional accessor on `MastraCodePluginContext` returns the host's `storage` (`MastraCompositeStore`), `storageBackend` (`'libsql' | 'pg'`), and optional `vector` (`MastraVector`). Call it when the tool runs, then pass the returned object to `bootLocalAgentController()`:
+
+```typescript
+import { bootLocalAgentController } from '@mastra/code-sdk'
+import type { MastraCodePluginContext } from '@mastra/code-sdk/plugin'
+
+async function bootNestedController(context: MastraCodePluginContext) {
+  const sharedStorage = context.getStorage?.()
+  if (!sharedStorage) {
+    throw new Error('This plugin requires host-provided shared storage.')
+  }
+  return bootLocalAgentController({ cwd: context.cwd, ...sharedStorage })
+}
+```
+
+The host owns these instances. Stop the nested controller's workers and destroy its controller when finished, but don't close the borrowed stores or invoke its storage-maintenance methods. If the accessor is unavailable on an older host, don't fall back to opening the same database files.
+
 ## Related
 
 - [AgentController class](https://mastra.ai/reference/agent-controller/agent-controller-class)

package/.docs/reference/core/getMCPServer.md

@@ -38,6 +38,53 @@ const serverById = mastra.getMCPServerById('my-mcp-server')
 
 **server** (`MCPServerBase | undefined`): The MCP server instance with the specified registry key, or undefined if not found.
 
+## MCP 1.x and 2026-07-28 servers
+
+Both `@mastra/mcp` 1.x and 2.x servers extend the same `MCPServerBase` from `@mastra/core/mcp`. A 2.x server sets `mcpVersion` to `2`, while 1.x servers leave it undefined and need no new properties or methods. The differences are limited to what the 2026-07-28 protocol changed: `startSSE` and `startHonoSSE` are no longer abstract and throw unless a 1.x server overrides them (only 1.x implements the standalone SSE transport, and both are deprecated), and a server with `mcpVersion` set to `2` resolves `executeTool` to a `MCPToolExecutionResultV2` that reports a suspended tool rather than a bare result.
+
+The 1.x-only surfaces are marked `@deprecated` and are removed in the next major release of `@mastra/core`: `startSSE`, `startHonoSSE`, `MCPServerSSEOptions`, `MCPServerHonoSSEOptions`, `MCPServerHTTPOptions.options`, and on `context.mcp` the members `elicitation`, `extra.sendNotification` and `extra.sendRequest`.
+
+### Tools that ask for input
+
+A 2026-07-28 server runs ordinary `createTool` definitions. A tool that needs something from the user before it can finish declares `suspendSchema` and `resumeSchema` and calls `suspend()`, exactly as it would for an agent or a workflow. Core reports the suspension as `{ status: 'suspended', suspendPayload, resumeSchema }` from `executeTool`. An `@mastra/mcp` 2.x server turns that into an `input_required` round on the wire, and resumes the tool with the answer in `resumeData`.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+const confirm = createTool({
+  id: 'confirm',
+  description: 'Ask for confirmation before charging',
+  inputSchema: z.object({ amount: z.number() }),
+  outputSchema: z.boolean(),
+  suspendSchema: z.object({ phase: z.literal('confirm'), amount: z.number() }),
+  resumeSchema: z.object({ confirmed: z.boolean() }),
+  execute: async ({ amount }, context) => {
+    if (!context.resumeData) {
+      await context.suspend?.({ phase: 'confirm', amount })
+      return
+    }
+    return context.resumeData.confirmed
+  },
+})
+```
+
+On a 2026-07-28 server and in direct execution, `suspend`, `resumeData` and `suspendPayload` sit at the top level of the tool context. Agents and workflows still nest them under `context.agent` and `context.workflow` until the next major release of `@mastra/core`. `resumeSchema` must be a flat object of primitive fields so it can be presented as an input form.
+
+Each round is a separate request. `resumeData` carries only the current round's answer, validated against `resumeSchema`, and `suspendPayload` carries what the tool last suspended with. Because the framework never replays earlier rounds, handlers branch on explicit named phases, every round is re-authorized, and writes rely on domain-owned idempotency. `suspendPayload` is also handed back to tools resumed by agents and workflows.
+
+### The `mcp` context
+
+Both server versions hand a tool the same `context.mcp` (`MCPToolExecutionContext`): `extra` with the request's `signal`, `requestId`, `authInfo` and `_meta`, plus `log(level, message, data?)` and `progress({ progress, total?, message? })`. A tool that only uses these works unchanged on either version. A 2026-07-28 server also sets `context.mcp.protocolVersion` to `'2026-07-28'`.
+
+The 2026-07-28 protocol removed server-initiated requests, so on a 2.x server the deprecated members `elicitation.sendRequest`, `extra.sendRequest` and `extra.sendNotification` throw with a message naming the replacement instead of doing nothing. A 1.x server keeps providing them as before. To ask the user for input, call `context.suspend()` and read `context.resumeData`.
+
+### Registration and execution
+
+Tools are registered on the Mastra instance exactly as a 1.x server registers them. On a server with `mcpVersion` set to `2`, `executeTool(toolId, args, context?)` returns `{ status: 'completed', output }` or, when the tool suspended, `{ status: 'suspended', suspendPayload, resumeSchema }` with `resumeSchema` as JSON Schema. The result has no failure variant: a tool that throws, or input or resume data that fails its schema, rejects the promise. Shared REST execution endpoints return the suspended shape instead of pretending the tool finished, and accept `resumeData` plus the echoed `suspendPayload` on the next call to continue the tool. Legacy SSE routes remain available only to 1.x servers. A server with `mcpVersion` set to `2` gets a 404 there.
+
+Registering another server under an occupied registry key keeps the existing instance. Registry keys and intrinsic server IDs remain distinct.
+
 ## Related methods
 
 - [Mastra.getMCPServerById()](https://mastra.ai/reference/core/getMCPServerById): Retrieve an MCP server by its intrinsic `id` property

package/.docs/reference/index.md

@@ -229,6 +229,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.settled()](https://mastra.ai/reference/memory/settled)
 - [.summarizeThread()](https://mastra.ai/reference/memory/summarizeThread)
 - [.updateThreadResourceId()](https://mastra.ai/reference/memory/updateThreadResourceId)
+- [@mastra/mcp v1 to v2](https://mastra.ai/reference/migrations/mcp-v2)
 - [AgentNetwork to .network()](https://mastra.ai/reference/migrations/agentnetwork)
 - [AI SDK v4 to v5](https://mastra.ai/reference/migrations/ai-sdk-v4-to-v5)
 - [Mastra Cloud to Mastra platform](https://mastra.ai/reference/migrations/mastra-cloud)
@@ -352,6 +353,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Task tools](https://mastra.ai/reference/tools/task-tools)
 - [Amazon S3 Vector Store](https://mastra.ai/reference/vectors/s3vectors)
 - [Astra Vector Store](https://mastra.ai/reference/vectors/astra)
+- [Azure AI Search Vector Store](https://mastra.ai/reference/vectors/azure-ai-search)
 - [Chroma Vector Store](https://mastra.ai/reference/vectors/chroma)
 - [Cloudflare Vector Store](https://mastra.ai/reference/vectors/vectorize)
 - [Convex Vector Store](https://mastra.ai/reference/vectors/convex)
@@ -368,6 +370,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Qdrant Vector Store](https://mastra.ai/reference/vectors/qdrant)
 - [Turbopuffer Vector Store](https://mastra.ai/reference/vectors/turbopuffer)
 - [Upstash Vector Store](https://mastra.ai/reference/vectors/upstash)
+- [Weaviate Vector Store](https://mastra.ai/reference/vectors/weaviate)
 - [Overview](https://mastra.ai/reference/voice/overview)
 - [Composite Voice](https://mastra.ai/reference/voice/composite-voice)
 - [Events](https://mastra.ai/reference/voice/voice.events)

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

@@ -41,6 +41,8 @@ export const agent = new Agent({
 
 **options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable the message history feature entirely (messages are not loaded into context or saved). Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To load messages without saving new ones, use the readOnly option. The window slides forward on every request, so once a thread exceeds the limit, each turn invalidates the provider prompt cache. For long-running conversations, use Observational Memory instead.
 
+**options.messageHistory** (`{ maxTokens: number; atMaxRemoveTokens?: number }`): Token budget for the complete prompt, including remembered history, system instructions, context, and the current turn. When the prompt exceeds maxTokens, the oldest remembered messages are dropped until the prompt is at most maxTokens - atMaxRemoveTokens (defaults to 25% of maxTokens). Protected content is never removed. Linked tool calls and results are removed together. During agent runs, trimmed history is excluded from later turns via a persisted per-thread boundary, but the messages themselves stay in storage. When set without an explicit lastMessages, the default 10-message cap is not applied. Set maxTokens to 0 to disable message history. Prefer this over lastMessages, since message count is a poor proxy for context size.
+
 **options.readOnly** (`boolean`): When true, prevents memory from saving new messages and provides working memory as read-only context (without the updateWorkingMemory tool). Useful for read-only operations like previews, internal routing agents, or sub agents that should reference but not modify memory.
 
 **options.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): Enable semantic search in message history. Can be a boolean or an object with configuration options. When enabled, requires both vector store and embedder to be configured. Default topK is 4, default messageRange is {before: 1, after: 1}.
@@ -49,7 +51,7 @@ export const agent = new Agent({
 
 **options.observationalMemory** (`boolean | ObservationalMemoryOptions`): Enable Observational Memory for long-context agentic memory. Set to true for defaults, or pass a config object to customize token budgets, models, and scope. See Observational Memory reference for configuration details.
 
-**options.generateTitle** (`boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }`): Controls automatic thread title generation from the conversation transcript. Can be a boolean or an object with custom model and instructions.
+**options.generateTitle** (`boolean | { model?: DynamicArgument<MastraModelConfig>; instructions?: DynamicArgument<string>; minMessages?: number; emitEvent?: boolean }`): Controls automatic thread title generation from the conversation transcript. Accepts a boolean or an object with a custom model (any MastraModelConfig: a model instance, a "provider/model" ID, or an OpenAI-compatible config; defaults to the agent's own model), custom instructions, a minimum message count, and emitEvent. With emitEvent: true the run's stream waits for the title and emits it as a transient data-thread-title chunk before finish (durable and evented agents persist the title but don't emit the chunk yet).
 
 ## Returns