@mastra/mcp-docs-server 1.2.7-alpha.8 → 1.2.8-alpha.0

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -23,13 +23,13 @@ If metrics aren't available, see [troubleshooting](#troubleshooting).
 
 Duration metrics record execution time in milliseconds, calculated from the span's start and end timestamps. Each duration metric includes a `status` label set to `ok` or `error`, derived from the span's status.
 
-| Metric name                    | Span type                    | Description                                             |
-| ------------------------------ | ---------------------------- | ------------------------------------------------------- |
-| `mastra_agent_duration_ms`     | `AGENT_RUN`                  | Execution time of an agent run                          |
-| `mastra_tool_duration_ms`      | `TOOL_CALL`, `MCP_TOOL_CALL` | Execution time of a tool call, including MCP tool calls |
-| `mastra_workflow_duration_ms`  | `WORKFLOW_RUN`               | Execution time of a workflow run                        |
-| `mastra_model_duration_ms`     | `MODEL_GENERATION`           | Execution time of a model generation                    |
-| `mastra_processor_duration_ms` | `PROCESSOR_RUN`              | Execution time of a processor run                       |
+| Metric name                    | Span type                                          | Description                                                                   |
+| ------------------------------ | -------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `mastra_agent_duration_ms`     | `AGENT_RUN`                                        | Execution time of an agent run                                                |
+| `mastra_tool_duration_ms`      | `TOOL_CALL`, `MCP_TOOL_CALL`, `PROVIDER_TOOL_CALL` | Execution time of a tool call, including MCP and provider-executed tool calls |
+| `mastra_workflow_duration_ms`  | `WORKFLOW_RUN`                                     | Execution time of a workflow run                                              |
+| `mastra_model_duration_ms`     | `MODEL_GENERATION`                                 | Execution time of a model generation                                          |
+| `mastra_processor_duration_ms` | `PROCESSOR_RUN`                                    | Execution time of a processor run                                             |
 
 ## Token usage metrics
 
@@ -124,7 +124,7 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
 ### Duration metrics are missing
 
 - **Span has timestamps**: Duration is calculated from `startTime` and `endTime`. If either is missing, the metric is skipped.
-- **Span type maps to a metric**: Only `AGENT_RUN`, `TOOL_CALL`, `MCP_TOOL_CALL`, `WORKFLOW_RUN`, `MODEL_GENERATION`, and `PROCESSOR_RUN` spans produce duration metrics.
+- **Span type maps to a metric**: Only `AGENT_RUN`, `TOOL_CALL`, `MCP_TOOL_CALL`, `PROVIDER_TOOL_CALL`, `WORKFLOW_RUN`, `MODEL_GENERATION`, and `PROCESSOR_RUN` spans produce duration metrics.
 
 ### Token metrics are missing
 

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

@@ -92,6 +92,7 @@ const exporter = new BraintrustExporter({
 | `MODEL_CHUNK`               | `llm`           |
 | `TOOL_CALL`                 | `tool`          |
 | `MCP_TOOL_CALL`             | `tool`          |
+| `PROVIDER_TOOL_CALL`        | `tool`          |
 | `WORKFLOW_CONDITIONAL_EVAL` | `function`      |
 | `WORKFLOW_WAIT_EVENT`       | `function`      |
 | All others                  | `task`          |

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

@@ -95,15 +95,16 @@ const exporter = new DatadogExporter({
 
 Mastra span types are mapped to Datadog LLM Observability span kinds:
 
-| Mastra SpanType    | Datadog Kind |
-| ------------------ | ------------ |
-| `AGENT_RUN`        | `agent`      |
-| `MODEL_GENERATION` | `workflow`   |
-| `MODEL_STEP`       | `llm`        |
-| `TOOL_CALL`        | `tool`       |
-| `MCP_TOOL_CALL`    | `tool`       |
-| `WORKFLOW_RUN`     | `workflow`   |
-| All other types    | `task`       |
+| Mastra SpanType      | Datadog Kind |
+| -------------------- | ------------ |
+| `AGENT_RUN`          | `agent`      |
+| `MODEL_GENERATION`   | `workflow`   |
+| `MODEL_STEP`         | `llm`        |
+| `TOOL_CALL`          | `tool`       |
+| `MCP_TOOL_CALL`      | `tool`       |
+| `PROVIDER_TOOL_CALL` | `tool`       |
+| `WORKFLOW_RUN`       | `workflow`   |
+| All other types      | `task`       |
 
 All unmapped span types (including `MODEL_CHUNK`, `WORKFLOW_STEP`, `GENERIC`, and future span types) automatically default to `task`.
 

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

@@ -73,13 +73,14 @@ const exporter = new LangSmithExporter({
 
 ## Span type mapping
 
-| Span Type          | LangSmith Type |
-| ------------------ | -------------- |
-| `MODEL_GENERATION` | `llm`          |
-| `MODEL_CHUNK`      | `llm`          |
-| `TOOL_CALL`        | `tool`         |
-| `MCP_TOOL_CALL`    | `tool`         |
-| All others         | `chain`        |
+| Span Type            | LangSmith Type |
+| -------------------- | -------------- |
+| `MODEL_GENERATION`   | `llm`          |
+| `MODEL_CHUNK`        | `llm`          |
+| `TOOL_CALL`          | `tool`         |
+| `MCP_TOOL_CALL`      | `tool`         |
+| `PROVIDER_TOOL_CALL` | `tool`         |
+| All others           | `chain`        |
 
 ## `withLangsmithMetadata`
 

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

@@ -80,15 +80,16 @@ const exporter = new PosthogExporter({
 
 ## Span type mapping
 
-| Mastra Span Type    | PostHog Event Type |
-| ------------------- | ------------------ |
-| `MODEL_GENERATION`  | `$ai_generation`   |
-| `MODEL_STEP`        | `$ai_generation`   |
-| `MODEL_CHUNK`       | `$ai_span`         |
-| `TOOL_CALL`         | `$ai_span`         |
-| `MCP_TOOL_CALL`     | `$ai_span`         |
-| `PROCESSOR_RUN`     | `$ai_span`         |
-| `AGENT_RUN`         | `$ai_span`         |
-| `WORKFLOW_RUN`      | `$ai_span`         |
-| All other workflows | `$ai_span`         |
-| `GENERIC`           | `$ai_span`         |
+| Mastra Span Type     | PostHog Event Type |
+| -------------------- | ------------------ |
+| `MODEL_GENERATION`   | `$ai_generation`   |
+| `MODEL_STEP`         | `$ai_generation`   |
+| `MODEL_CHUNK`        | `$ai_span`         |
+| `TOOL_CALL`          | `$ai_span`         |
+| `MCP_TOOL_CALL`      | `$ai_span`         |
+| `PROVIDER_TOOL_CALL` | `$ai_span`         |
+| `PROCESSOR_RUN`      | `$ai_span`         |
+| `AGENT_RUN`          | `$ai_span`         |
+| `WORKFLOW_RUN`       | `$ai_span`         |
+| All other workflows  | `$ai_span`         |
+| `GENERIC`            | `$ai_span`         |

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

@@ -117,6 +117,7 @@ Mastra span types are mapped to Sentry operations:
 | `MODEL_CHUNK`               | _(skipped)_            |
 | `TOOL_CALL`                 | `gen_ai.execute_tool`  |
 | `MCP_TOOL_CALL`             | `gen_ai.execute_tool`  |
+| `PROVIDER_TOOL_CALL`        | `gen_ai.execute_tool`  |
 | `WORKFLOW_RUN`              | `workflow.run`         |
 | `WORKFLOW_STEP`             | `workflow.step`        |
 | `WORKFLOW_CONDITIONAL`      | `workflow.conditional` |

package/.docs/reference/observability/tracing/interfaces.md

@@ -46,6 +46,7 @@ interface SpanTypeMap {
   MODEL_CHUNK: ModelChunkAttributes
   TOOL_CALL: ToolCallAttributes
   CLIENT_TOOL_CALL: ClientToolCallAttributes
+  PROVIDER_TOOL_CALL: ProviderToolCallAttributes
   MCP_TOOL_CALL: MCPToolCallAttributes
   PROCESSOR_RUN: ProcessorRunAttributes
   WORKFLOW_STEP: WorkflowStepAttributes
@@ -314,6 +315,14 @@ enum SpanType {
    */
   CLIENT_TOOL_CALL = 'client_tool_call',
 
+  /**
+   * Provider-executed (server-side) tool span. Reconstructed from
+   * tool-call and tool-result stream chunks for tools the model
+   * provider executes (e.g. Anthropic code execution, server-side
+   * web search). Opened on tool-call chunk, closed on tool-result.
+   */
+  PROVIDER_TOOL_CALL = 'provider_tool_call',
+
   /** Workflow run - root span for workflow processes */
   WORKFLOW_RUN = 'workflow_run',
 

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

@@ -2,9 +2,9 @@
 
 # StreamErrorRetryProcessor
 
-`StreamErrorRetryProcessor` is an **error processor** that retries transient errors emitted after an LLM stream starts. It includes built-in matching for OpenAI Responses stream errors and supports additional matchers for other provider-specific stream error shapes.
+`StreamErrorRetryProcessor` is an **error processor** that retries transient LLM API and stream failures. It includes built-in matching for OpenAI Responses stream errors and supports additional matchers for other provider-specific error shapes.
 
-The processor isn't enabled by default in core. Add it to `errorProcessors` for agents that need stream-error retry handling.
+The processor isn't enabled by default in core. Add it to `errorProcessors` for agents that need bounded retry handling.
 
 ## Usage example
 
@@ -35,6 +35,43 @@ When the error is retryable, the processor returns `{ retry: true }`. It doesn't
 
 When `delayMs` is set, the processor waits before signaling a retry. This is useful for transient network errors like `ECONNRESET` where immediately retrying is likely to fail again. The delay can be a fixed number of milliseconds or a function evaluated with the error args (for example, to implement exponential backoff).
 
+### Retry limits
+
+`maxRetries` defaults to `1` and limits this processor's retry requests. The agent also limits processor retries with `maxProcessorRetries`. When error processors are configured without an agent limit, the runtime cap is `10`.
+
+Set both values explicitly to the same bounded value when you need a single retry budget. Keep model `maxRetries` at `0` for that call to avoid multiplying provider attempts.
+
+### `Retry-After` handling
+
+For retryable errors with a `Retry-After` response header, the processor reads case-insensitive delta-seconds and HTTP-date values through the error cause chain. It waits for the longer of `delayMs` and the bounded server delay.
+
+`maxRetryAfterMs` defaults to `30_000`. It caps only provider-provided wait time. A longer explicit `delayMs` remains unchanged. Invalid or expired headers are ignored.
+
+## Retry unknown errors
+
+Set `retryUnknownErrors` to retry errors that don't match provider metadata, the built-in OpenAI matcher, or a custom matcher. Unknown-error retries use the processor-level `maxRetries` and `delayMs` values. Known authorization failures, including HTTP `401` and `403` responses, aren't retried:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { StreamErrorRetryProcessor } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  id: 'resilient-agent',
+  name: 'Resilient agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5',
+  errorProcessors: [
+    new StreamErrorRetryProcessor({
+      retryUnknownErrors: true,
+      maxRetries: 2,
+      delayMs: 3000,
+    }),
+  ],
+})
+```
+
+Specific matcher policies still take precedence over the unknown-error values. The option defaults to `false`, so unknown errors aren't retried unless you enable it.
+
 ## Delaying retries
 
 Use `delayMs` with a custom matcher to retry transient network resets with a wait:

package/.docs/reference/pubsub/base.md

@@ -101,6 +101,16 @@ Waits for any in-flight deliveries to settle. Call this before shutdown to avoid
 await pubsub.flush()
 ```
 
+#### `clearTopic(topic)`
+
+Deletes all retained state for a topic — cached history, persistent stream entries, and consumer groups — once no more events will be published to it. Mastra's run lifecycles (durable agents and the evented workflow engine) call this automatically when a run reaches a terminal state, so per-run topics don't accumulate on transports that retain messages.
+
+The default implementation is a no-op: transports that retain nothing per topic (such as `EventEmitterPubSub`) have nothing to clear. Backends that persist messages, like [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), override it. The contract is best-effort — implementations log failures rather than throwing, because callers invoke it fire-and-forget at cleanup boundaries.
+
+```typescript
+await pubsub.clearTopic('workflow.events.v2.run-123')
+```
+
 ### Replay methods
 
 These methods support resuming a stream after a disconnect. The default implementations fall back to a regular `subscribe`, so backends without history support behave as live-only. [`CachingPubSub`](https://mastra.ai/reference/pubsub/caching-pubsub) overrides them to replay cached events.

package/.docs/reference/pubsub/caching-pubsub.md

@@ -92,6 +92,14 @@ const events = await pubsub.getHistory('my-topic', 0)
 
 Returns: `Promise<Event[]>`
 
+### `clearTopic(topic)`
+
+Removes the topic's cached events and offset counter, and forwards the call to the inner pub/sub so persistent transports (such as [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams)) can delete their retained state too. Mastra's run lifecycles call this automatically when a run finishes.
+
+```typescript
+await pubsub.clearTopic('my-topic')
+```
+
 ## Functions
 
 ### `withCaching(pubsub, cache, options?)`

package/.docs/reference/pubsub/redis-streams.md

@@ -63,6 +63,8 @@ export const mastra = new Mastra({
 
 **maxStreamLength** (`number`): Approximate maximum number of entries kept per stream. Set to 0 to disable trimming. (Default: `10000`)
 
+**streamIdleTtlMs** (`number`): Idle expiry in milliseconds: a sliding TTL refreshed on every write (publish, nack retry, group re-creation). Each write resets it, so an actively-written stream never expires mid-flight; a stream left idle for the full duration is deleted by Redis automatically. Note that only writes refresh the TTL — a consumer slowly draining a backlog does not — so set it well above the longest expected gap between writes on a live topic. This is a backstop, not the primary cleanup — clearTopic handles normal end-of-lifecycle deletion; this only bounds memory for streams that never reach a clearTopic call (e.g. a crashed run). Must be a non-negative integer. Defaults to 0 (disabled). (Default: `0`)
+
 **reclaimIntervalMs** (`number`): How often, in milliseconds, a subscription reclaims events that an earlier consumer read but never acknowledged. Set to 0 to disable. (Default: `30000`)
 
 **reclaimIdleMs** (`number`): Minimum idle time, in milliseconds, before a pending event is eligible for reclaim. Keep this well above typical processing time to avoid double delivery. (Default: `60000`)
@@ -97,6 +99,16 @@ Waits for in-flight publishes to complete.
 await pubsub.flush()
 ```
 
+### `clearTopic(topic)`
+
+Deletes a topic's stream and every consumer group on it, freeing the memory a finished topic would otherwise hold. Mastra's run lifecycles — durable agents and the evented workflow engine — call this automatically when a run reaches a terminal state; call it yourself only once nothing will read the topic again. It's best-effort and never throws — failures are logged at warn level. A subscriber still attached when the stream is deleted recovers on its own but misses the deleted entries.
+
+Automatic cleanup requires `@mastra/core` and `@mastra/redis-streams` versions that both support `clearTopic`: the runtime routes the call through its caching layer, so upgrade the two packages together to get end-of-run stream deletion.
+
+```typescript
+await pubsub.clearTopic('workflow.events.run-123')
+```
+
 ### `close()`
 
 Closes the Redis connections and stops all subscriptions. Call this during graceful shutdown.

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

@@ -2,9 +2,7 @@
 
 # Express adapter
 
-The `@mastra/express` package provides a server adapter for running Mastra with [Express](https://expressjs.com).
-
-> **Info:** For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+The `@mastra/express` package provides a server adapter for running Mastra with [Express](https://expressjs.com). For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Installation
 

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

@@ -2,9 +2,7 @@
 
 # Fastify adapter
 
-The `@mastra/fastify` package provides a server adapter for running Mastra with [Fastify](https://fastify.dev).
-
-> **Info:** For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+The `@mastra/fastify` package provides a server adapter for running Mastra with [Fastify](https://fastify.dev). For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Installation
 

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

@@ -2,9 +2,7 @@
 
 # Hono adapter
 
-The `@mastra/hono` package provides a server adapter for running Mastra with [Hono](https://hono.dev).
-
-> **Info:** For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+The `@mastra/hono` package provides a server adapter for running Mastra with [Hono](https://hono.dev). For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Installation
 

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

@@ -2,9 +2,7 @@
 
 # Koa adapter
 
-The `@mastra/koa` package provides a server adapter for running Mastra with [Koa](https://koajs.com).
-
-> **Info:** For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+The `@mastra/koa` package provides a server adapter for running Mastra with [Koa](https://koajs.com). For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Installation
 

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

@@ -4,9 +4,7 @@
 
 The `@mastra/nestjs` package provides a NestJS module for running Mastra with the Express-based NestJS platform.
 
-It's intentionally Express-only for v1. If Nest is bootstrapped with a different HTTP adapter, `MastraModule` throws during startup instead of attempting a partial integration.
-
-> **Info:** For general adapter concepts, see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+It's intentionally Express-only for v1. If Nest is bootstrapped with a different HTTP adapter, `MastraModule` throws during startup instead of attempting a partial integration. For general adapter concepts, see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Installation
 

package/.docs/reference/server/register-api-route.md

@@ -28,7 +28,7 @@ registerApiRoute("/items/:itemId", { ... })
 
 **handler** (`Handler`): Route handler function receiving Hono Context. Use either handler or createHandler, not both.
 
-**createHandler** (`(c: Context) => Promise<Handler>`): Async factory function to create the handler. Use either handler or createHandler, not both.
+**createHandler** (`({ mastra }: { mastra: Mastra }) => Promise<ApiRouteHandler>`): Async factory that receives the Mastra instance and returns the route handler. Runs once at server startup, so it can perform one-time setup. Use either handler or createHandler, not both.
 
 **middleware** (`MiddlewareHandler | MiddlewareHandler[]`): Route-specific middleware functions
 
@@ -229,12 +229,13 @@ For routes that need async initialization:
 ```typescript
 registerApiRoute('/dynamic', {
   method: 'GET',
-  createHandler: async c => {
-    // Perform async setup
+  createHandler: async ({ mastra }) => {
+    // Perform one-time async setup
     const config = await loadConfig()
+    const agent = mastra.getAgent('weatherAgent')
 
     return async c => {
-      return c.json({ config })
+      return c.json({ config, agent: agent.name })
     }
   },
 })

package/.docs/reference/templates/overview.md

@@ -15,7 +15,7 @@ Mastra templates are pre-built project structures that demonstrate specific use
 
 The following templates demonstrate Gateway-first Mastra applications:
 
-- `template-docs-expert`: Answers documentation questions with Mastra Gateway web search, citations, memory, and structured responses.
+- `template-docs-expert`: Answers documentation questions with Gateway web search, citations, memory, and structured responses.
 - `template-browser-agent`: Uses AgentBrowser to browse, inspect, and interact with web pages.
 - `template-meeting-notes`: Turns Zoom transcripts or uploaded transcripts into structured notes with decisions and action items.
 - `template-company-knowledge`: Indexes Linear and Notion content into pgvector and answers internal knowledge questions.

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