@mastra/mcp-docs-server 1.2.7-alpha.1 → 1.2.7-alpha.12

package/.docs/reference/storage/mongodb.md

@@ -32,7 +32,7 @@ bun add @mastra/mongodb@latest
 
 ## Usage
 
-Ensure you have a MongoDB Atlas Local (via Docker) or MongoDB Atlas Cloud instance with Atlas Search enabled. MongoDB 7.0+ is recommended.
+Ensure you have a [MongoDB Atlas Local (via Docker)](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/) or [MongoDB Atlas Cloud](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-getting-started/) instance with Atlas Search enabled. MongoDB 7.0+ is recommended.
 
 ```typescript
 import { MongoDBStore } from '@mastra/mongodb'
@@ -40,7 +40,7 @@ import { MongoDBStore } from '@mastra/mongodb'
 const storage = new MongoDBStore({
   id: 'mongodb-storage',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 ```
 
@@ -54,7 +54,15 @@ const storage = new MongoDBStore({
 
 **dbName** (`string`): The name of the database you want the storage to use.
 
-**options** (`MongoClientOptions`): MongoDB client options for advanced configuration (SSL, connection pooling, etc.).
+**options** (`MongoClientOptions`): MongoDB client options for advanced configuration (SSL, connection pooling, etc.). See Connection Options
+
+**disableInit** (`boolean`): When true, automatic initialization (collection creation) is disabled. Useful for CI/CD pipelines where you want to run migrations explicitly. You must call storage.init() manually when this is true.
+
+**skipDefaultIndexes** (`boolean`): When true, default indexes will not be created during initialization. Useful when managing indexes separately or using only custom indexes.
+
+**indexes** (`MongoDBIndexConfig[]`): Custom indexes to create during initialization. Each index must specify a collection, keys, and optional index options. See Indexes
+
+**connectorHandler** (`ConnectorHandler`): Custom connection handler for advanced connection management. Alternative to providing uri/dbName directly.
 
 > **Deprecation Notice:** The `url` parameter is deprecated but still supported for backward compatibility. Please use `uri` instead in all new code.
 
@@ -84,6 +92,26 @@ const store2 = new MongoDBStore({
     socketTimeoutMS: 45000,
   },
 })
+
+// With custom indexes
+const store3 = new MongoDBStore({
+  id: 'mongodb-storage-03',
+  uri: 'mongodb+srv://user:password@cluster.mongodb.net',
+  dbName: 'mastra_storage',
+  indexes: [
+    { collection: 'mastra_threads', keys: { 'metadata.type': 1 } },
+    { collection: 'mastra_messages', keys: { 'metadata.status': 1 }, options: { sparse: true } },
+  ],
+})
+
+// For CI/CD with explicit initialization
+const store4 = new MongoDBStore({
+  id: 'mongodb-storage-04',
+  uri: 'mongodb+srv://user:password@cluster.mongodb.net',
+  dbName: 'mastra_storage',
+  disableInit: true, // Disable auto-init
+})
+await store4.init() // Call init explicitly
 ```
 
 ## Additional notes
@@ -114,7 +142,7 @@ import { MongoDBStore } from '@mastra/mongodb'
 const storage = new MongoDBStore({
   id: 'mongodb-storage',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 
 const mastra = new Mastra({
@@ -130,7 +158,7 @@ import { MongoDBStore } from '@mastra/mongodb'
 const storage = new MongoDBStore({
   id: 'mongodb-storage',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 
 // Required when using storage directly
@@ -143,57 +171,28 @@ const thread = await memoryStore?.getThreadById({ threadId: '...' })
 
 > **Warning:** If `init()` isn't called, collections won't be created and storage operations will fail silently or throw errors.
 
-## Vector search capabilities
-
-MongoDB storage includes built-in vector search capabilities for AI applications:
+### Connection Management
 
-### Vector Index Creation
+The `close()` method closes the MongoDB client connection. Call this when shutting down your application:
 
 ```typescript
-import { MongoDBVector } from '@mastra/mongodb'
+import { MongoDBStore } from '@mastra/mongodb'
 
-const vectorStore = new MongoDBVector({
-  id: 'mongodb-vector',
+const storage = new MongoDBStore({
+  id: 'mongodb-storage',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 
-// Create a vector index for embeddings
-await vectorStore.createIndex({
-  indexName: 'document_embeddings',
-  dimension: 1536,
-})
+// Use storage...
+
+// Clean up on shutdown
+await storage.close()
 ```
 
-### Vector Operations
+## Vector search capabilities
 
-```typescript
-// Store vectors with metadata
-await vectorStore.upsert({
-  indexName: "document_embeddings",
-  vectors: [
-    {
-      id: "doc-1",
-      values: [0.1, 0.2, 0.3, ...], // 1536-dimensional vector
-      metadata: {
-        title: "Document Title",
-        category: "technical",
-        source: "api-docs",
-      },
-    },
-  ],
-});
-
-// Similarity search
-const results = await vectorStore.query({
-  indexName: "document_embeddings",
-  vector: queryEmbedding,
-  topK: 5,
-  filter: {
-    category: "technical",
-  },
-});
-```
+MongoDB storage includes built-in vector search capabilities for AI applications. For detailed vector operations including index creation, upserting embeddings, similarity search, and metadata filtering, see the [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb).
 
 ## Usage example
 
@@ -214,6 +213,7 @@ export const mongodbAgent = new Agent({
   model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new MongoDBStore({
+      id: 'mongodb-storage',
       uri: process.env.MONGODB_URI!,
       dbName: process.env.MONGODB_DB_NAME!,
     }),

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

@@ -6,7 +6,7 @@ Storage grows without bound by default. Retention is an opt-in, age-based cleanu
 
 `prune()` deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable). It never reclaims disk — on SQLite/libSQL the freed pages are reused by future writes so the file stops growing, but handing disk back to the OS (for example a `VACUUM`) is left to the underlying database and the operator to manage.
 
-Retention covers **growth tables** only — tables that accumulate rows unbounded as a side effect of normal operation (conversation history, telemetry, job and run records, schedule fire history, event feeds). User-authored artifacts and config (agents, skills, workspaces, prompt blocks, datasets, schedule definitions, channel installations, and so on) grow with user intent and are edited or deleted explicitly, so they are not valid retention keys.
+Retention covers **growth tables** only — tables that accumulate rows unbounded as a side effect of normal operation (conversation history, telemetry, job and run records, schedule fire history, event feeds). User-authored artifacts and config (agents, skills, workspaces, prompt blocks, datasets, schedule definitions, channel installations, and so on) grow with user intent and are edited or deleted explicitly, so they're not valid retention keys.
 
 The reference implementations are [libSQL](https://mastra.ai/reference/storage/libsql), [PostgreSQL](https://mastra.ai/reference/storage/postgresql), and [MongoDB](https://mastra.ai/reference/storage/mongodb). Other adapters keep rows forever until they implement retention.
 
@@ -89,8 +89,8 @@ Each domain declares which of its tables can be age-pruned and which timestamp c
 > **Note:**
 >
 > - The memory `observational_memory` table has no timestamp anchor, so it can't be age-pruned and isn't a valid retention key.
-> - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. There is no separate `results` key.
-> - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire) — schedule definitions are config and are not pruned.
+> - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. Retention doesn't have a separate `results` key.
+> - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire) — schedule definitions are config and aren't pruned.
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
 > - LibSQL supports all domains above; PostgreSQL and MongoDB support all except `threadState` and `harness`, which they don't implement.
 > - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows — effective granularity is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
@@ -105,6 +105,8 @@ Deletes rows older than their configured `maxAge` across every domain that has a
 
 `prune()` is designed to be safe on tables with millions of rows. It deletes in bounded, batched chunks — each batch is its own transaction — so it never takes a long lock or bloats the transaction log. It never runs a `VACUUM`.
 
+Pass `options.retention` to replace the configured policies for that call only — for example to skip a domain (keep chat history) or prune more aggressively than the standing config. The store's configured `retention` is unchanged.
+
 Anchor-column indexes are created lazily on the first `prune()` call for each table with a policy — never at `init()` — so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build; subsequent prunes reuse the index.
 
 ```typescript
@@ -116,6 +118,13 @@ const results = await storage.prune({
 for (const r of results) {
   console.log(`${r.domain}.${r.table}: deleted ${r.deleted}, done=${r.done}`)
 }
+
+// One-off pass with different policies (configured retention untouched):
+await storage.prune({
+  retention: {
+    observability: { spans: { maxAge: '1d' } },
+  },
+})
 ```
 
 Returns: `Promise<PruneResult[]>`
@@ -130,6 +139,8 @@ Returns: `Promise<PruneResult[]>`
 
 **signal** (`AbortSignal`): Cooperative cancellation. The batch loop checks it between batches and stops cleanly, returning partial results with done: false.
 
+**retention** (`RetentionConfig`): Replaces the store's configured retention policies for this call only — e.g. to skip a domain or prune more aggressively. The configured retention is unchanged.
+
 ##### PruneResult
 
 Each result describes one table's progress:
@@ -145,7 +156,7 @@ interface PruneResult {
 
 ## Running prune on a schedule
 
-`prune()` has no built-in scheduler — you decide when it runs. Because it is bounded, a single call may not delete everything. When any result has `done: false`, eligible rows remain and you call again on the next tick. This keeps each invocation short and lets a large backlog drain over several runs.
+`prune()` has no built-in scheduler — you decide when it runs. Because it's bounded, a single call may not delete everything. When any result has `done: false`, eligible rows remain and you call again on the next tick. This keeps each invocation short and lets a large backlog drain over several runs.
 
 ```typescript
 // Runs on your own cron (node-cron, a workflow schedule, an external job, etc.).
@@ -164,11 +175,68 @@ async function retentionTick() {
 
 You can also cancel a long-running prune with an `AbortSignal` — the loop stops between batches and returns partial results with `done: false`, so the next run resumes cleanly.
 
+## MongoDB TTL indexes (alternative to prune)
+
+MongoDB offers native [TTL (Time-To-Live) indexes](https://www.mongodb.com/docs/manual/core/index-ttl/) that automatically delete expired documents without requiring manual `prune()` calls. This is a database-level feature that runs as a background thread.
+
+> **When to use TTL vs prune():** **Use MongoDB TTL indexes when:**
+>
+> - You want automated, zero-maintenance deletion
+> - Your retention periods are fixed (e.g., "always 30 days")
+> - You prefer database-native solutions
+>
+> **Use `prune()` when:**
+>
+> - You need fine-grained control over deletion timing
+> - You want to cap deletion rate during business hours
+> - You need resumable, cancellable cleanup operations
+> - You're using composite storage with multiple databases
+>
+> Both approaches are valid. TTL is simpler; `prune()` gives more control.
+
+### Setting up TTL indexes on MongoDB
+
+TTL indexes work on date fields. MongoDB checks the index every 60 seconds and deletes documents where the date field + TTL duration < current time.
+
+```typescript
+import { MongoDBStore } from '@mastra/mongodb'
+
+const storage = new MongoDBStore({
+  id: 'mongodb-storage',
+  uri: process.env.MONGODB_URI!,
+  dbName: process.env.MONGODB_DB_NAME!,
+  indexes: [
+    // Messages expire after 30 days
+    {
+      collection: 'mastra_messages',
+      keys: { createdAt: 1 },
+      options: { expireAfterSeconds: 30 * 24 * 60 * 60 }, // 30 days
+    },
+    // Threads expire after 90 days
+    {
+      collection: 'mastra_threads',
+      keys: { createdAt: 1 },
+      options: { expireAfterSeconds: 90 * 24 * 60 * 60 }, // 90 days
+    },
+    // Spans expire after 7 days
+    {
+      collection: 'mastra_ai_spans',
+      keys: { startedAt: 1 },
+      options: { expireAfterSeconds: 7 * 24 * 60 * 60 }, // 7 days
+    },
+  ],
+})
+```
+
+> **Tip:** TTL indexes delete documents shortly after they expire (background thread runs every \~60 seconds), but the exact timing is not guaranteed. For precise, immediate cleanup, use `prune()` instead.
+
 ## Reclaiming disk
 
-`prune()` deletes rows but does not 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.
+`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 does not 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.
 
 > **LibSQL and Turso:** [Turso Cloud](https://mastra.ai/reference/storage/libsql) manages storage compaction for you, so there's nothing to reclaim manually. This applies only to self-hosted libSQL files.
 

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

@@ -87,7 +87,7 @@ export const tool = createTool({
 
 **onOutput** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Signature: ({ output, toolName, ...options }: { output: TSchemaOut; toolName: string } & Omit\<ToolCallOptions, 'messages'>) => void | PromiseLike\<void>.
 
-Runtime-populated fields such as `mastra` and `mcpMetadata` appear in source types but are set by Mastra or MCP adapters. You do not need to configure them for ordinary `createTool()` usage.
+Runtime-populated fields such as `mastra` and `mcpMetadata` appear in source types but are set by Mastra or MCP adapters. You don't need to configure them for ordinary `createTool()` usage.
 
 ## Returns
 
@@ -450,7 +450,7 @@ Hook callbacks receive these source-backed parameter shapes:
 - `onInputStart`: Receives `ToolCallOptions`, including fields such as `toolCallId`, `messages`, and `abortSignal`.
 - `onInputDelta`: Receives `{ inputTextDelta: string } & ToolCallOptions`.
 - `onInputAvailable`: Receives `{ input: TSchemaIn } & ToolCallOptions`, where `input` is typed from `inputSchema`.
-- `onOutput`: Receives `{ output: TSchemaOut; toolName: string } & Omit<ToolCallOptions, 'messages'>`, where `output` is typed from `outputSchema`. This hook does not receive `messages`.
+- `onOutput`: Receives `{ output: TSchemaOut; toolName: string } & Omit<ToolCallOptions, 'messages'>`, where `output` is typed from `outputSchema`. This hook doesn't receive `messages`.
 
 ### Error handling
 

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

@@ -601,6 +601,28 @@ mcpClient.prompts.onListChanged('myWeatherServer', () => {
 })
 ```
 
+### `tools` Property
+
+The `MCPClient` instance has a `tools` property for subscribing to tool list change notifications. To fetch tools, use `listTools()` or `listToolsets()`.
+
+#### `tools.onListChanged(serverName: string, handler: () => void)`
+
+Sets a notification handler that will be called when the list of available tools changes on a specific server (for example, when the server adds or removes tools at runtime).
+
+```typescript
+async onListChanged(serverName: string, handler: () => void): Promise<void>
+```
+
+Example:
+
+```typescript
+await mcpClient.tools.onListChanged('myWeatherServer', async () => {
+  console.log('Tool list changed on myWeatherServer.')
+  // You should re-fetch the tools
+  // const tools = await mcpClient.listTools();
+})
+```
+
 ### `progress` Property
 
 The `MCPClient` instance has a `progress` property for subscribing to progress notifications emitted by MCP servers while tools execute.

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

@@ -399,12 +399,31 @@ serve(async req => {
 >
 > The serverless mode disables session management and creates fresh server instances per request, which is necessary for stateless environments where memory doesn't persist between invocations.
 >
-> **Note:** The following MCP features require session state or persistent connections and **won't work** in serverless mode:
+> By default, serverless mode buffers each request into a single JSON response, so `notifications/progress` sent by a tool never reach the client. Set `serverlessStreaming: true` to handle the request with request-scoped SSE streaming instead, which delivers progress notifications before the final result:
+>
+> ```typescript
+> await server.startHTTP({
+>   url,
+>   httpPath: '/mcp',
+>   req: nodeReq,
+>   res: nodeRes,
+>   options: {
+>     serverless: true,
+>     serverlessStreaming: true, // ← Stream request-scoped notifications/progress
+>   },
+> })
+> ```
+>
+> 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.
+>
+> **Note:** 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
 > - **Resource update notifications** - `resources.notifyUpdated()` requires active subscriptions and persistent connections to notify clients
 > - **Prompt list change notifications** - `prompts.notifyListChanged()` requires persistent connections to push updates to clients
+> - **Tool list change notifications** - `toolActions.notifyListChanged()` requires persistent connections to push updates to clients
+> - **Server log notifications** - `sendLoggingMessage()` requires persistent connections to push log messages to clients
 >
 > These features work normally in long-lived server environments (Node.js servers, Docker containers, etc.).
 
@@ -424,6 +443,8 @@ The `StreamableHTTPServerTransportOptions` object allows you to customize the be
 
 **serverless** (`boolean`): If true, runs in stateless mode without session management. Each request is handled independently with a fresh server instance. Essential for serverless environments (Cloudflare Workers, Supabase Edge Functions, Vercel Edge, etc.) where sessions cannot persist between invocations. Defaults to false.
 
+**serverlessStreaming** (`boolean`): If true, serverless requests use request-scoped SSE streaming instead of a buffered JSON response, allowing in-request notifications/progress to reach the client before the final result. Only takes effect together with serverless: true. Defaults to false (buffered JSON responses), which preserves backward-compatible behavior. This enables only request-scoped notifications such as progress; elicitation, subscriptions, and out-of-request notifications still require session state.
+
 **sessionIdGenerator** (`(() => string) | undefined`): A function that generates a unique session ID. This should be a cryptographically secure, globally unique string. Return undefined to disable session management.
 
 **onsessioninitialized** (`(sessionId: string) => void`): A callback that is invoked when a new session is initialized. This is useful for tracking active MCP sessions.
@@ -776,6 +797,144 @@ await serverWithPrompts.prompts.notifyListChanged()
 - Handle errors with informative messages.
 - Document argument expectations and available versions.
 
+## Dynamic tool management
+
+Tools are usually provided when constructing the `MCPServer`, but you can also add or remove tools while the server is running. The server exposes these operations through the `toolActions` property. When the tool list changes, connected clients receive a `notifications/tools/list_changed` message prompting them to re-fetch the tool list.
+
+The property is named `toolActions` because `tools()` is the method that returns the registered tool registry.
+
+### `toolActions.add(tools)`
+
+Registers new tools on the running server and notifies connected clients. Tools are keyed by their record key, the same as tools passed to the constructor. Adding a tool under an existing key replaces it.
+
+```typescript
+async server.toolActions.add(tools: ToolsInput): Promise<void>
+```
+
+Example:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+const searchTool = createTool({
+  id: 'search',
+  description: 'Searches the knowledge base.',
+  inputSchema: z.object({ query: z.string() }),
+  execute: async ({ query }) => ({ results: [] }),
+})
+
+await server.toolActions.add({ searchTool })
+```
+
+### `toolActions.remove(toolIds)`
+
+Removes tools from the running server by tool ID and notifies connected clients. Unknown tool IDs are ignored. If no tools were removed, no notification is sent.
+
+```typescript
+async server.toolActions.remove(toolIds: string[]): Promise<void>
+```
+
+Example:
+
+```typescript
+await server.toolActions.remove(['searchTool'])
+```
+
+### `toolActions.notifyListChanged()`
+
+Sends a `notifications/tools/list_changed` message to connected clients without modifying the tool registry. Call this when tool availability changes through other means (for example, authorization changes).
+
+```typescript
+async server.toolActions.notifyListChanged(): Promise<void>
+```
+
+### Mastra registry synchronization
+
+When the server is registered with a Mastra instance, `toolActions.add()` and `toolActions.remove()` also update the Mastra instance's tool registry, matching the automatic tool registration that happens at startup. Added tools become available through `mastra.listTools()` (keyed by the tool's intrinsic `id` when present), and removed tools are deleted from the registry.
+
+## Logging
+
+MCP servers can send structured log messages to clients using `notifications/message`. Clients control verbosity by sending a `logging/setLevel` request; the server drops messages below the requested minimum level (following RFC 5424 severity ordering). The level is tracked per session, so different clients can request different verbosity.
+
+### `sendLoggingMessage()`
+
+Sends a log notification to all connected clients, honoring each client's minimum logging level.
+
+```typescript
+async server.sendLoggingMessage(params: {
+  level: LoggingLevel;
+  data: unknown;
+  logger?: string;
+}): Promise<void>
+```
+
+Example:
+
+```typescript
+await server.sendLoggingMessage({
+  level: 'info',
+  data: { message: 'Sync completed', itemsProcessed: 42 },
+})
+```
+
+### `context.mcp.log()`
+
+Inside a tool's `execute` function, use `context.mcp.log()` to send a log message to the client that called the tool.
+
+```typescript
+async context.mcp.log(
+  level: LoggingLevel,
+  message: string,
+  data?: Record<string, unknown>
+): Promise<void>
+```
+
+Example:
+
+```typescript
+execute: async ({ location }, context) => {
+  await context.mcp.log('debug', 'Fetching weather', { location })
+  const weather = await fetchWeather(location)
+  await context.mcp.log('info', 'Weather fetched')
+  return weather
+}
+```
+
+## Progress notifications
+
+Long-running tools can report progress to the calling client with `notifications/progress`. Progress is only sent when the caller requested progress tracking by including a `progressToken` in the request (the Mastra `MCPClient` does this when `enableProgressTracking` is set). When no token was sent, `context.mcp.progress()` is a no-op.
+
+### `context.mcp.progress()`
+
+```typescript
+async context.mcp.progress(params: {
+  progress: number;
+  total?: number;
+  message?: string;
+}): Promise<void>
+```
+
+Example:
+
+```typescript
+execute: async ({ items }, context) => {
+  for (const [index, item] of items.entries()) {
+    await processItem(item)
+    await context.mcp.progress({
+      progress: index + 1,
+      total: items.length,
+      message: `Processed ${item.name}`,
+    })
+  }
+  return { done: true }
+}
+```
+
+## Notification delivery
+
+Notification methods (`resources.notifyListChanged()`, `prompts.notifyListChanged()`, `toolActions.notifyListChanged()`, and `sendLoggingMessage()`) broadcast to every connected client across all transports: the stdio/SSE connection and each streamable HTTP session. `resources.notifyUpdated()` is the exception: it only notifies clients that subscribed to the resource URI via `resources/subscribe`. Subscriptions are tracked per session for streamable HTTP clients; legacy SSE clients share the main server instance and therefore share one subscription set. Clients using the stateless serverless mode can't receive notifications because each request uses a transient server instance.
+
 ## Examples
 
 For practical examples of setting up and deploying an MCPServer, see the [Publishing an MCP Server guide](https://mastra.ai/guides/guide/publishing-mcp-server).
@@ -1402,9 +1561,7 @@ const server = new MCPServer({
 })
 ```
 
-Link a tool to its app resource by setting `_meta.ui.resourceUri` on the tool to the matching `ui://` URI. The server auto-normalizes this metadata when registering tools.
-
-> **Note:** Visit [MCP Apps](https://mastra.ai/docs/mcp/mcp-apps) for the full app bridge API and usage patterns.
+Link a tool to its app resource by setting `_meta.ui.resourceUri` on the tool to the matching `ui://` URI. The server auto-normalizes this metadata when registering tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/mcp-apps) for the full app bridge API and usage patterns.
 
 ## Related information