@mastra/mcp-docs-server 1.2.17-alpha.9 → 1.2.18-alpha.1

package/.docs/reference/rag/graph-rag.md

@@ -9,10 +9,7 @@ The `GraphRAG` class implements a graph-based approach to retrieval augmented ge
 ```typescript
 import { GraphRAG } from '@mastra/rag'
 
-const graphRag = new GraphRAG({
-  dimension: 1536,
-  threshold: 0.7,
-})
+const graphRag = new GraphRAG(1536, 0.7)
 
 // Create the graph from chunks and embeddings
 graphRag.createGraph(documentChunks, embeddings)
@@ -88,13 +85,79 @@ Returns an array of `RankedNode` objects, where each node contains:
 
 **score** (`number`): Combined relevance score from graph traversal
 
+### `serialize`
+
+Returns a JSON-safe snapshot of the graph so it can be persisted and restored later instead of rebuilt with `createGraph`.
+
+```typescript
+serialize(): GraphRAGSnapshot
+```
+
+#### Returns
+
+Returns a `GraphRAGSnapshot` object containing:
+
+**version** (`number`): Snapshot format version, used to reject snapshots this version of the class can't load
+
+**dimension** (`number`): Dimension of the embedding vectors the graph was built with
+
+**threshold** (`number`): Similarity threshold the graph was built with
+
+**nodes** (`GraphNode[]`): All nodes in the graph, each including its full embedding
+
+**edges** (`GraphEdge[]`): All edges in the graph
+
+The snapshot is a deep copy, so mutating it doesn't affect the graph it came from. Every node carries its full embedding, so snapshots are large: a 1,000-node graph built with 1536-dimension embeddings serializes to about 20 MB of JSON. Size your storage column accordingly.
+
+### `deserialize`
+
+Rebuilds a `GraphRAG` instance from a snapshot produced by `serialize`.
+
+```typescript
+static deserialize(snapshot: GraphRAGSnapshot): GraphRAG
+```
+
+#### Parameters
+
+**snapshot** (`GraphRAGSnapshot`): A snapshot previously returned by serialize
+
+Throws if the snapshot version is unsupported, if a node embedding doesn't match the snapshot dimension, or if an edge references a node that isn't in the snapshot. A bad snapshot therefore fails at load time instead of during a later query.
+
+## Persisting a graph
+
+Building a graph is O(n²) in the number of chunks, so rebuilding it on every process start is wasteful. Serialize the graph once and store the snapshot wherever you already keep state. A snapshot is plain JSON, so any store works (a file, a blob column, a key-value cache), and `GraphRAG` doesn't depend on a storage backend.
+
+```typescript
+import { readFile, writeFile } from 'node:fs/promises'
+import { GraphRAG } from '@mastra/rag'
+import type { GraphRAGSnapshot } from '@mastra/rag'
+
+const SNAPSHOT_PATH = './docs-graph.json'
+
+async function loadOrBuildGraph() {
+  try {
+    const snapshot = JSON.parse(await readFile(SNAPSHOT_PATH, 'utf8')) as GraphRAGSnapshot
+    return GraphRAG.deserialize(snapshot)
+  } catch {
+    // No usable snapshot yet, so build the graph from scratch
+  }
+
+  const graphRag = new GraphRAG(1536, 0.7)
+  graphRag.createGraph(documentChunks, embeddings)
+
+  await writeFile(SNAPSHOT_PATH, JSON.stringify(graphRag.serialize()))
+
+  return graphRag
+}
+```
+
+A snapshot reflects the chunks it was built from and isn't updated incrementally. When the underlying documents change, build the graph again and store a new snapshot.
+
 ## Advanced example
 
 ```typescript
-const graphRag = new GraphRAG({
-  dimension: 1536,
-  threshold: 0.8, // Stricter similarity threshold
-})
+// Stricter similarity threshold
+const graphRag = new GraphRAG(1536, 0.8)
 
 // Create graph from chunks and embeddings
 graphRag.createGraph(documentChunks, embeddings)

package/.docs/reference/rag/retrieval.md

@@ -266,6 +266,23 @@ For detailed configuration options and advanced usage, see the [Vector Query Too
 
 Vector store prompts define query patterns and filtering capabilities for each vector database implementation. When implementing filtering, these prompts are required in the agent's instructions to specify valid operators and syntax for each vector store implementation.
 
+**MongoDB**:
+
+```ts
+import { MONGODB_PROMPT } from '@mastra/mongodb'
+
+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.
+  ${MONGODB_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+})
+```
+
 **pgVector**:
 
 ```ts
@@ -402,23 +419,6 @@ export const ragAgent = new Agent({
 })
 ```
 
-**MongoDB**:
-
-```ts
-import { MONGODB_PROMPT } from '@mastra/mongodb'
-
-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.
-  ${MONGODB_PROMPT}
-  `,
-  tools: { vectorQueryTool },
-})
-```
-
 **OpenSearch**:
 
 ```ts
@@ -520,7 +520,13 @@ The weights control how different factors influence the final ranking:
 
 > **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
 
-You can also use other relevance score providers like Cohere or ZeroEntropy:
+You can also use other relevance score providers like Voyage AI, Cohere, or ZeroEntropy:
+
+```ts
+import { VoyageRelevanceScorer } from '@mastra/voyageai'
+
+const relevanceProvider = new VoyageRelevanceScorer({ model: 'rerank-2.5' })
+```
 
 ```ts
 const relevanceProvider = new CohereRelevanceScorer('rerank-v3.5')
@@ -530,6 +536,8 @@ const relevanceProvider = new CohereRelevanceScorer('rerank-v3.5')
 const relevanceProvider = new ZeroEntropyRelevanceScorer('zerank-1')
 ```
 
+Voyage AI provides dedicated reranking models: `rerank-2.5` and `rerank-2.5-lite` both allow up to 32,000 tokens for the query and any single document combined, and up to 600,000 tokens across a request. `VoyageRelevanceScorer` reads `VOYAGE_API_KEY` from the environment, or accepts an `apiKey` in its config.
+
 The re-ranked results combine vector similarity with semantic understanding to improve retrieval quality.
 
 For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/rag/rerankWithScorer) method.

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

@@ -8,7 +8,7 @@
 
 `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).
+For usage patterns and concepts, see [Schedules](https://mastra.ai/docs/harness/schedules).
 
 ## Usage example
 

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

@@ -402,7 +402,7 @@ Contains output from workflow step execution, used primarily for usage tracking
 
 ## Background task chunks
 
-Emitted when a tool call is dispatched as a [background task](https://mastra.ai/docs/long-running-agents/background-tasks) and `streamUntilIdle()` is used.
+Emitted when a tool call is dispatched as a [background task](https://mastra.ai/docs/harness/background-tasks) and `streamUntilIdle()` is used.
 
 ### background-task-started
 
@@ -614,7 +614,7 @@ Contains monitoring and observability data from agent execution. Can include wor
 
 ### goal
 
-Emitted on every evaluation of an agent [goal](https://mastra.ai/docs/long-running-agents/goals). Consumers use this to render judge progress and the result mid-run. A goal that has no judge model configured produces no `goal` chunk.
+Emitted on every evaluation of an agent [goal](https://mastra.ai/docs/harness/goals). Consumers use this to render judge progress and the result mid-run. A goal that has no judge model configured produces no `goal` chunk.
 
 **type** (`"goal"`): Chunk type identifier
 

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

@@ -80,7 +80,7 @@ const stream = await agent.stream('message for agent')
 
 **options.onError** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback function called when an error occurs during streaming.
 
-**options.onAbort** (`(event: any) => Promise<void> | void`): Callback function called when the stream is aborted.
+**options.onAbort** (`(event: { steps: any[]; text?: string }) => Promise<void> | void`): Callback function called when the stream is aborted. steps contains the steps that completed before the abort, and text contains the assistant text streamed so far for the step that was in flight.
 
 **options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated, including any in-flight subagent runs the agent delegated to.
 
@@ -158,6 +158,8 @@ const stream = await agent.stream('message for agent')
 
 **options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
 
+**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured.
+
 **options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
 
 **options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): Controls how the agent uses tools during streaming.
@@ -178,6 +180,8 @@ const stream = await agent.stream('message for agent')
 
 **options.savePerStep** (`boolean`): Save messages incrementally after each stream step completes (default: false).
 
+**options.persistPartialOnAbort** (`boolean`): Save the assistant text that was streamed before an abort to memory (default: false). Only text emitted before the abort is persisted; output a provider keeps producing after cancellation is discarded, and nothing is saved when no text was streamed.
+
 **options.requireToolApproval** (`boolean`): When true, all tool calls require explicit approval before execution. The stream will emit tool-call-approval chunks and pause until approveToolCall() or declineToolCall() is called.
 
 **options.autoResumeSuspendedTools** (`boolean`): When true, automatically resumes suspended tools when the user sends a new message on the same thread. The agent extracts resumeData from the user's message based on the tool's resumeSchema. Requires memory to be configured.
@@ -262,6 +266,26 @@ for await (const chunk of stream.fullStream) {
 const fullText = await stream.text
 ```
 
+### Limiting execution time
+
+Use `modelSettings.timeout` to bound how long a run may take. `totalMs` limits the entire run, including every loop iteration, tool call and retry. `stepMs` limits a single model call, covering both establishing the stream and consuming it.
+
+```ts
+const stream = await agent.stream('Tell me a story', {
+  modelSettings: {
+    timeout: {
+      totalMs: 30000, // fail the run if it takes longer than 30s
+      stepMs: 10000, // fail an individual model call after 10s
+    },
+  },
+})
+```
+
+Exceeding either budget fails with a `MastraTimeoutError`, which carries a `timeoutType` of `'total'` or `'step'`. Each budget behaves differently when the agent is configured with fallback [`models`](https://mastra.ai/reference/agents/agent):
+
+- A `totalMs` timeout ends the run immediately and doesn't try the next model, because it's a hard deadline for the run as a whole.
+- A `stepMs` timeout isn't retried against the same model, but does advance to the next model, which makes it a way to fail over from a slow provider.
+
 ### AI SDK v5+ Format
 
 To use the stream with AI SDK v5 (and later), you can convert it using our utility function `toAISdkStream`.
@@ -301,8 +325,9 @@ const stream = await agent.stream('Tell me a story', {
   onError: ({ error }) => {
     console.error('Streaming error:', error)
   },
-  onAbort: event => {
-    console.log('Stream aborted:', event)
+  onAbort: ({ steps, text }) => {
+    console.log('Stream aborted after', steps.length, 'steps')
+    console.log('Partial text:', text)
   },
 })
 
@@ -399,4 +424,4 @@ Responses WebSocket connections run one response at a time. Mastra rejects overl
 
 - [Generating responses](https://mastra.ai/docs/agents/overview)
 - [Streaming responses](https://mastra.ai/docs/agents/overview)
-- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
+- [Agent Approval](https://mastra.ai/docs/agents/human-in-the-loop)

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

@@ -101,7 +101,7 @@ for await (const chunk of stream.fullStream) {
 
 ## Related
 
-- [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks)
+- [Background tasks](https://mastra.ai/docs/harness/background-tasks)
 - [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
 - [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
 - [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)

package/.docs/reference/tools/ask-user-tool.md

@@ -4,7 +4,7 @@
 
 A built-in, agent-agnostic tool that asks the user a question and waits for their response. The tool supports free-text questions, single-select prompts, and multi-select prompts.
 
-The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/agent-approval) primitive: it calls `suspend()` with the question payload, which makes the agent emit a `tool-call-suspended` event and persist run state. Resume the run with `agent.resumeStream(answer, { runId })`.
+The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/human-in-the-loop) primitive: it calls `suspend()` with the question payload, which makes the agent emit a `tool-call-suspended` event and persist run state. Resume the run with `agent.resumeStream(answer, { runId })`.
 
 When executed outside an agent run (no `suspend` available), the tool returns a readable fallback string containing the question and choices.
 

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

@@ -126,4 +126,4 @@ export const codeModeTool = createCodeModeTool({
 
 - [Code mode](https://mastra.ai/docs/agents/code-mode)
 - [createTool()](https://mastra.ai/reference/tools/create-tool)
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)

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

@@ -519,8 +519,8 @@ These annotations follow the [MCP specification](https://spec.modelcontextprotoc
 
 ## Related
 
-- [MCP Overview](https://mastra.ai/docs/mcp/overview)
-- [Using Tools with Agents](https://mastra.ai/docs/agents/using-tools)
-- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
-- [Tool Streaming](https://mastra.ai/docs/agents/using-tools)
+- [MCP Overview](https://mastra.ai/docs/connections/mcp)
+- [Using Tools with Agents](https://mastra.ai/docs/agents/tools)
+- [Agent Approval](https://mastra.ai/docs/agents/human-in-the-loop)
+- [Tool Streaming](https://mastra.ai/docs/agents/tools)
 - [Request Context](https://mastra.ai/docs/server/request-context)

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

@@ -65,6 +65,8 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
 
 **requireToolApproval** (`boolean | (params: RequireToolApprovalContext) => boolean | Promise<boolean>`): Require human approval before executing tools from this server. When set to true, all tools require approval. When set to a function, the function is called with the tool name, arguments, request context, and any tool annotations advertised by the server to dynamically decide whether approval is needed.
 
+**protocolVersion** (`'auto' | '2026-07-28'`): Opt-in MCP protocol version negotiation. Omitted keeps the legacy (2025-era) connect sequence unchanged. 'auto' probes the server at connect time and uses the stateless '2026-07-28' revision when the server supports it, with a safe fallback to the legacy handshake. '2026-07-28' pins that revision exactly and fails with a typed error when the server does not offer it. Elicitation handlers work on both eras: on a '2026-07-28' connection, embedded elicitation requests from input\_required results are dispatched through the same registered handler and the originating call retries automatically.
+
 ## Tool approval
 
 Use `requireToolApproval` on a server definition to require human approval before any tool from that server is executed. This works with the existing [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) approval flow.

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

@@ -91,6 +91,35 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
 
 **appResources** (`AppResources`): A map of ui:// URIs to app resource configurations. Each entry defines an interactive HTML UI served via the MCP Apps extension (SEP-1865). See the MCP Apps section for details.
 
+**protocolVersion** (`'2025-11-25' | '2026-07-28'`): Opt-in MCP protocol revision. Omitted (or '2025-11-25') keeps the legacy behavior exactly. Set to '2026-07-28' to serve the stateless MCP revision. See the Protocol versions section for details.
+
+**cacheHints** (`MCPServerCacheHints`): Cache hints (ttlMs / cacheScope) advertised on cacheable results of the '2026-07-28' protocol revision, keyed by operation (e.g. 'tools/list'). Only applied when protocolVersion: '2026-07-28' is set.
+
+## Protocol versions
+
+By default, `MCPServer` speaks the legacy (2025-era) MCP protocol: sessionful streamable HTTP with an `initialize` handshake. Set `protocolVersion: '2026-07-28'` to serve the stateless MCP revision instead:
+
+- HTTP and serverless requests go through a dual-era handler: clients that speak `2026-07-28` are served natively (stateless, per-request envelope), and legacy clients are served through a built-in stateless fallback on the same endpoint.
+- `startStdio()` serves both eras: the opening exchange selects the era for the connection.
+- Tool list, prompt list, resource list, and resource update notifications also reach `2026-07-28` clients through `subscriptions/listen`.
+- Tool log messages honor the caller's per-request `logLevel` opt-in instead of the session-level `logging/setLevel`.
+- Configured `cacheHints` are advertised on cacheable results such as `tools/list`.
+- Tool elicitation (`options.mcp.elicitation.sendRequest()`) works on both eras. On `2026-07-28` requests, it uses the protocol's multi round-trip mechanism. The tool call first returns an `input_required` result. After the client answers, the call retries with the answer attached. The `sendRequest()` promise API is unchanged, but the tool function re-executes from the top on each retry, so keep side effects idempotent (or place them after the last elicitation) and keep the order of `sendRequest()` calls deterministic for an input.
+
+```typescript
+const server = new MCPServer({
+  name: 'My Server',
+  version: '1.0.0',
+  tools: { weatherTool },
+  protocolVersion: '2026-07-28',
+  cacheHints: {
+    'tools/list': { ttlMs: 60_000, cacheScope: 'private' },
+  },
+})
+```
+
+Omitting `protocolVersion` keeps the current behavior unchanged.
+
 ## Exposing agents as tools
 
 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:
@@ -168,6 +197,51 @@ const fetchUserData = createTool({
 })
 ```
 
+#### Where `authInfo` comes from
+
+When an MCP server is served by a Mastra server, `extra.authInfo` is populated from the principal resolved by `server.auth`. Nothing extra is required:
+
+```typescript
+export const mastra = new Mastra({
+  mcpServers: { myServer },
+  server: {
+    auth: new MastraJwtAuth({ secret: process.env.JWT_SECRET! }),
+  },
+})
+```
+
+The authenticated user is mapped to `authInfo` as:
+
+| `authInfo` field | Value                                                                      |
+| ---------------- | -------------------------------------------------------------------------- |
+| `token`          | The bearer token or session cookie value used for the request              |
+| `clientId`       | The first present of `user.id`, `user.sub`, `user.userId`, `user.email`    |
+| `scopes`         | `user.scopes`, `user.scope`, or `user.permissions`, normalized to an array |
+| `extra.user`     | The full user object returned by the auth provider                         |
+
+If your own middleware performs the verification, set `server.mcpOptions.setRequestAuth` to build `authInfo` yourself. The hook replaces the default mapping and applies to both the streamable HTTP and SSE transports:
+
+```typescript
+export const mastra = new Mastra({
+  mcpServers: { myServer },
+  server: {
+    middleware: [verifyBearerToken], // stores the payload on the request context
+    mcpOptions: {
+      setRequestAuth: (req, requestContext) => {
+        const payload = requestContext.get('bearerPayload')
+        req.auth = {
+          token: payload.token,
+          clientId: payload.sub,
+          scopes: payload.scope.split(' '),
+        }
+      },
+    },
+  },
+})
+```
+
+Leaving `req.auth` unset inside the hook opts the request out of auth info entirely.
+
 ## Methods
 
 These are the functions you can call on an `MCPServer` instance to control its behavior and get information.
@@ -194,6 +268,8 @@ await server.startStdio()
 
 ### `startSSE()`
 
+> **Warning:** The HTTP+SSE transport is deprecated in the MCP specification. Use `startHTTP()` (streamable HTTP) instead.
+
 This method helps you integrate the MCP server with an existing web server to use Server-Sent Events (SSE) for communication. You'll call this from your web server's code when it receives a request for the SSE or message paths.
 
 ```typescript
@@ -246,6 +322,8 @@ Here are the details for the values needed by the `startSSE` method:
 
 ### `startHonoSSE()`
 
+> **Warning:** The HTTP+SSE transport is deprecated in the MCP specification. Use `startHTTP()` (streamable HTTP) instead.
+
 This method helps you integrate the MCP server with an existing web server to use Server-Sent Events (SSE) for communication. You'll call this from your web server's code when it receives a request for the SSE or message paths.
 
 ```typescript
@@ -316,6 +394,21 @@ async startHTTP({
 }): Promise<void>
 ```
 
+#### Options with `protocolVersion: '2026-07-28'`
+
+The `2026-07-28` protocol uses one shared stateless handler instead of a transport configured for each request. `startHTTP()` handles legacy transport options as follows:
+
+| Options                                                                              | Behavior                                                                                                                                |
+| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `serverless: true`, `serverlessStreaming: true`, `sessionIdGenerator: undefined`     | Accepted because the modern handler already provides stateless requests and automatic request-scoped streaming.                         |
+| `allowedHosts`, `allowedOrigins`, `enableDnsRebindingProtection`                     | Enforced before the request reaches the modern handler. Host and origin lists are active when `enableDnsRebindingProtection` is `true`. |
+| `sessionIdGenerator` with a function, session callbacks, or `eventStore`             | Rejected because the modern protocol doesn't create HTTP sessions.                                                                      |
+| `enableJsonResponse`, `retryInterval`, `keepAliveMs`, or `supportedProtocolVersions` | Rejected because these values configure a shared handler and can't vary between requests.                                               |
+| `serverless: false` or `serverlessStreaming: false`                                  | Rejected because these values request behavior that differs from the modern handler.                                                    |
+| Unknown options                                                                      | Rejected instead of being ignored.                                                                                                      |
+
+Omit `options` when you don't need request guards or compatibility declarations.
+
 Here's an example of how you might use `startHTTP` within an HTTP server request handler. In this example an MCP client could connect to your MCP server at `http://localhost:1234/http`:
 
 ```typescript
@@ -338,7 +431,7 @@ httpServer.listen(PORT, () => {
 })
 ```
 
-For **serverless environments** (Supabase Edge Functions, Cloudflare Workers, Vercel Edge, etc.), use `serverless: true` to enable stateless operation:
+For **serverless environments** (Supabase Edge Functions, Cloudflare Workers, Vercel Edge, etc.), use `serverless: true` to enable stateless operation on the legacy protocol path. Servers configured with `protocolVersion: '2026-07-28'` are already stateless and may omit this option.
 
 ```typescript
 // Supabase Edge Function example
@@ -412,7 +505,7 @@ serve(async req => {
 >
 > This is still stateless: no `mcp-session-id` is required or persisted. It only enables notifications scoped to the current request (such as progress). The session-dependent features below remain unavailable.
 >
-> The following MCP features require session state or persistent connections and **won't work** in serverless mode (including with `serverlessStreaming: true`):
+> On the legacy protocol path, the following MCP features require session state or persistent connections and **won't work** in serverless mode (including with `serverlessStreaming: true`):
 >
 > - **Elicitation** - Interactive user input requests during tool execution require session management to route responses back to the correct client
 > - **Resource subscriptions** - `resources/subscribe` and `resources/unsubscribe` need persistent connections to maintain subscription state
@@ -929,7 +1022,7 @@ Notification methods (`resources.notifyListChanged()`, `prompts.notifyListChange
 
 ## Examples
 
-For a practical example of packaging a stdio server, see [Publish a stdio server package](https://mastra.ai/docs/mcp/overview).
+For a practical example of packaging a stdio server, see [Publish a stdio server package](https://mastra.ai/docs/connections/mcp).
 
 The example at the beginning of this page also demonstrates how to instantiate `MCPServer` with both tools and agents.
 
@@ -1663,7 +1756,7 @@ const server = new MCPServer({
 })
 ```
 
-Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `createTool()` to the matching `ui://` URI. The server normalizes this metadata for older hosts when listing tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/overview) for the full app bridge API and usage patterns.
+Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `createTool()` to the matching `ui://` URI. The server normalizes this metadata for older hosts when listing tools. Visit [MCP Apps](https://mastra.ai/docs/connections/mcp) for the full app bridge API and usage patterns.
 
 ## Related information
 

package/.docs/reference/tools/submit-plan-tool.md

@@ -4,7 +4,7 @@
 
 A built-in, agent-agnostic tool that submits an implementation plan for user review. The agent writes a plan to a markdown file and passes the file path to this tool. The tool suspends the run until the user approves or rejects the plan.
 
-The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/agent-approval) primitive: it calls `suspend({ path })`, which makes the agent emit a `tool-call-suspended` event. The host reads the plan file and presents it to the user. It then resumes with an approval or rejection.
+The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/human-in-the-loop) primitive: it calls `suspend({ path })`, which makes the agent emit a `tool-call-suspended` event. The host reads the plan file and presents it to the user. It then resumes with an approval or rejection.
 
 When executed outside an agent run (no `suspend` available), the tool returns a readable fallback string containing the file path.
 

package/.docs/reference/tools/task-tools.md

@@ -2,11 +2,11 @@
 
 # Task tools
 
-Four built-in, agent-agnostic tools that manage a structured task list for an agent run. The task list is persisted in the thread-scoped `threadState` storage domain and projected onto the agent [state-signal](https://mastra.ai/docs/long-running-agents/signals) lane so it survives [observational-memory](https://mastra.ai/docs/memory/observational-memory) truncation.
+Four built-in, agent-agnostic tools that manage a structured task list for an agent run. The task list is persisted in the thread-scoped `threadState` storage domain and projected onto the agent [state-signal](https://mastra.ai/docs/harness/signals) lane so it survives [observational-memory](https://mastra.ai/docs/memory/observational-memory) truncation.
 
 Task tracking requires a memory-backed thread (`threadId` + `resourceId`). Without memory the tools return an error explaining that task tracking requires agent memory.
 
-The recommended setup is [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider), which bundles all four tools and the `TaskStateProcessor` in a single registration. See [Built-in tools](https://mastra.ai/docs/agents/using-tools) for the conceptual guide.
+The recommended setup is [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider), which bundles all four tools and the `TaskStateProcessor` in a single registration. See [Built-in tools](https://mastra.ai/docs/agents/tools) for the conceptual guide.
 
 ## Usage example
 

package/.docs/reference/vectors/vectorize.md

@@ -90,13 +90,13 @@ Lists all metadata field indexes for an index.
 
 ### `updateVector()`
 
-Updates a vector or metadata for a specific ID within an index.
+Updates the vector and optionally the metadata for a specific ID within an index. Vectorize has no partial-update operation, so `update.vector` is required. Metadata-only updates aren't supported and throw an error.
 
 **indexName** (`string`): Name of the index containing the ID to update
 
 **id** (`string`): Unique identifier of the vector or metadata to update
 
-**update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): Object containing the vector and/or metadata to update
+**update** (`{ vector: number[]; metadata?: Record<string, any>; }`): Object containing the new vector values, and optionally the metadata to update. The vector values are required
 
 ### `deleteVector()`
 
@@ -106,6 +106,16 @@ Deletes a vector and its associated metadata for a specific ID within an index.
 
 **id** (`string`): Unique identifier of the vector and metadata to delete
 
+### `deleteVectors()`
+
+Deletes multiple vectors and their associated metadata by ID. Vectorize has no filtered-delete operation, so deleting by metadata filter isn't supported and throws an error.
+
+**indexName** (`string`): Name of the index containing the vectors to delete
+
+**ids** (`string[]`): Unique identifiers of the vectors to delete. Must contain at least one ID, and cannot be combined with filter
+
+**filter** (`Record<string, any>`): Not supported by Vectorize. Passing a filter throws an error
+
 ## Response types
 
 Query results are returned in this format:

package/.docs/reference/workers/overview.md

@@ -31,7 +31,7 @@ The base URL of the API server, used by the orchestration worker to execute work
 MASTRA_STEP_EXECUTION_URL=http://api:4111/api
 ```
 
-Use HTTPS URLs in production. See [Security recommendations](https://mastra.ai/docs/server/auth/workers).
+Use HTTPS URLs in production. See [Security recommendations](https://mastra.ai/docs/auth/workers).
 
 The orchestration worker sends step execution requests to:
 
@@ -41,7 +41,7 @@ ${MASTRA_STEP_EXECUTION_URL}/workflows/:workflowId/runs/:runId/steps/execute
 
 ### `MASTRA_WORKER_AUTH_TOKEN`
 
-A bearer token sent by the orchestration worker when calling the API's step execution endpoint. The API's configured auth provider must recognize this token. See [Worker authentication](https://mastra.ai/docs/server/auth/workers).
+A bearer token sent by the orchestration worker when calling the API's step execution endpoint. The API's configured auth provider must recognize this token. See [Worker authentication](https://mastra.ai/docs/auth/workers).
 
 ```text
 MASTRA_WORKER_AUTH_TOKEN=sk-worker-secret-token

package/.docs/reference/workflows/run-methods/resume.md

@@ -93,6 +93,27 @@ await run.resume({
 
 If `forEachIndex` is omitted, every suspended iteration of the step is resumed with the same `resumeData`.
 
+## Concurrent resume calls
+
+Only one `resume()` call can continue a suspension. Before it runs anything, `resume()` atomically claims the run by moving its stored status from `suspended` to `running`. If another caller already claimed it, this call throws `WORKFLOW_RESUME_ALREADY_CLAIMED` and executes no steps, so downstream steps and their side effects run once per suspension.
+
+This matters whenever a resume can be triggered more than once, such as an approval button pressed twice or a retried webhook. It also applies when several server instances react to the same event.
+
+```typescript
+try {
+  await run.resume({ step: 'approval', resumeData: { approved: true } })
+} catch (error) {
+  if (error.id === 'WORKFLOW_RESUME_ALREADY_CLAIMED') {
+    // Another caller is already continuing this run. Re-read the run state
+    // instead of resuming again.
+  }
+}
+```
+
+Over HTTP, a losing resume returns `409 Conflict`.
+
+> **Note:** The claim is enforced atomically by storage adapters that report `supportsConcurrentUpdates()`. Adapters without atomic read-modify-write support (such as ClickHouse, Cloudflare D1, Cloudflare KV, Cloudflare Durable Objects, LanceDB, and Redis) can't enforce it, and the claim is also skipped when `shouldPersistSnapshot` excludes the `running` status.
+
 ## Related
 
 - [Workflows overview](https://mastra.ai/docs/workflows/overview)

package/.docs/reference/workspace/local-filesystem.md

@@ -356,4 +356,4 @@ Set `WORKSPACE_PATH` in your environment to an absolute path like `/home/user/my
 
 - [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
 - [Workspace class](https://mastra.ai/reference/workspace/workspace-class)
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)

package/.docs/reference/workspace/local-sandbox.md

@@ -123,10 +123,11 @@ await sandbox.start()
 // Spawn a background process
 const handle = await sandbox.processes.spawn('node server.js')
 
-// Read output, send stdin, kill
+// Read output, send stdin, signal EOF, and wait for completion
 console.log(handle.stdout)
 await handle.sendStdin('input\n')
-await handle.kill()
+await handle.closeStdin()
+await handle.wait()
 ```
 
 When native isolation is enabled (`seatbelt` or `bwrap`), spawned processes are also wrapped with the same isolation backend.
@@ -223,4 +224,4 @@ This separation prevents sandboxed processes from reading or modifying their own
 - [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
 - [WorkspaceSandbox Interface](https://mastra.ai/reference/workspace/sandbox)
 - [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)