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

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

@@ -37,7 +37,7 @@ export const agent = new Agent({
 
 **options** (`MemoryConfig`): Memory configuration options.
 
-**options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable the message history feature entirely (messages are not loaded into context or saved). Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To load messages without saving new ones, use the readOnly option.
+**options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable loading conversation history into context. Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To prevent saving new messages, use the readOnly option instead.
 
 **options.readOnly** (`boolean`): When true, prevents memory from saving new messages and provides working memory as read-only context (without the updateWorkingMemory tool). Useful for read-only operations like previews, internal routing agents, or sub agents that should reference but not modify memory.
 

package/.docs/reference/memory/serialized-memory-config.md

@@ -38,7 +38,7 @@ new MastraEditor({
 
 **options.readOnly** (`boolean`): Treat memory as read-only — no new messages are stored.
 
-**options.lastMessages** (`number | false`): Number of recent messages to include in context, or false to disable message history entirely (messages are not loaded or saved).
+**options.lastMessages** (`number | false`): Number of recent messages to include in context, or false to disable.
 
 **options.semanticRecall** (`boolean | SemanticRecall`): Semantic recall configuration. See the Memory class reference for the full shape.
 

package/.docs/reference/project-structure.md

@@ -44,7 +44,7 @@ Mastra recommends organizing your code into the following folders:
 
 Mastra has two special folder conventions:
 
-- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [File-based Agents](https://mastra.ai/docs/getting-started/file-based-agents) docs.
+- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [file-based agents](https://mastra.ai/docs/agents/file-based-agents) guide.
 - `src/mastra/public`: Contents are copied into the `.build/output` directory during the build process, making them available for serving at runtime.
 
 ### Top-level files

package/.docs/reference/pubsub/lease-provider.md

@@ -130,4 +130,4 @@ When the configured pub/sub backend doesn't implement `LeaseProvider`, the runti
 - [PubSub](https://mastra.ai/reference/pubsub/base): The event delivery contract, separate from leasing
 - [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams): The built-in backend that implements `LeaseProvider`
 - [Signals](https://mastra.ai/docs/long-running-agents/signals): The runtime that uses leasing to coordinate thread runs across processes
-- [Channels](https://mastra.ai/docs/capabilities/channels/overview): Uses leasing to coordinate agent runs in serverless and multi-instance deployments
+- [Channels](https://mastra.ai/docs/agents/channels): Uses leasing to coordinate agent runs in serverless and multi-instance deployments

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

@@ -2,7 +2,9 @@
 
 # Express adapter
 
-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).
+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).
 
 ## Installation
 

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

@@ -2,7 +2,9 @@
 
 # Fastify adapter
 
-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).
+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).
 
 ## Installation
 

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

@@ -2,7 +2,9 @@
 
 # Hono adapter
 
-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).
+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).
 
 ## Installation
 

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

@@ -2,7 +2,9 @@
 
 # Koa adapter
 
-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).
+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).
 
 ## Installation
 

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

@@ -4,7 +4,9 @@
 
 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. 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.
+
+> **Info:** For general adapter concepts, see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Installation
 

package/.docs/reference/storage/clickhouse.md

@@ -101,38 +101,6 @@ const observabilityStore = new ObservabilityStorageClickhouse({
 
 New projects should use `ObservabilityStorageClickhouseVNext` instead.
 
-### Migrating from legacy to vNext
-
-To migrate historical spans from the legacy `mastra_ai_spans` table to the vNext schema, run:
-
-**npm**:
-
-```bash
-npx mastra migrate
-```
-
-**pnpm**:
-
-```bash
-pnpm dlx mastra migrate
-```
-
-**Yarn**:
-
-```bash
-yarn dlx mastra migrate
-```
-
-**Bun**:
-
-```bash
-bun x mastra migrate
-```
-
-The migration copies span data from `mastra_ai_spans` into `mastra_span_events` in day-sized batches. It handles column mapping, deduplicates legacy rows, and preserves the original table as a backup. After migration, traces appear in Studio through the vNext adapter.
-
-> **Note:** The legacy table is not deleted. Drop it manually after verifying the migration.
-
 ### ClickHouse for every domain
 
 `ClickhouseStoreVNext` backs the `memory`, `workflows`, and `observability` domains with ClickHouse and uses the vNext observability adapter automatically. Use it when you want ClickHouse to back the entire application without wiring a composite store manually.

package/.docs/reference/storage/composite.md

@@ -156,32 +156,6 @@ export const mastra = new Mastra({
 })
 ```
 
-### Disabling a domain
-
-Set a domain to `false` to disable it. A disabled domain doesn't fall back to `default`, so data for that domain isn't persisted:
-
-```typescript
-import { MastraCompositeStore } from '@mastra/core/storage'
-import { PostgresStore } from '@mastra/pg'
-import { Mastra } from '@mastra/core'
-
-const pgStore = new PostgresStore({
-  id: 'pg',
-  connectionString: process.env.DATABASE_URL,
-})
-
-export const mastra = new Mastra({
-  storage: new MastraCompositeStore({
-    id: 'composite',
-    default: pgStore,
-    domains: {
-      // don't persist traces and spans
-      observability: false,
-    },
-  }),
-})
-```
-
 ## Options
 
 **id** (`string`): Unique identifier for this storage instance.
@@ -190,7 +164,7 @@ export const mastra = new Mastra({
 
 **disableInit** (`boolean`): When true, automatic initialization is disabled. You must call init() explicitly.
 
-**domains** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over both editor and default storage. Set a domain to false to disable it entirely; a disabled domain does not fall back to editor or default.
+**domains** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over both editor and default storage.
 
 **domains.memory** (`MemoryStorage`): Storage for threads, messages, and resources.
 

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

@@ -105,8 +105,6 @@ 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
@@ -118,13 +116,6 @@ 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[]>`
@@ -139,8 +130,6 @@ 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:

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

@@ -601,28 +601,6 @@ 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,31 +399,12 @@ 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.
 >
-> 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`):
+> **Note:** The following MCP features require session state or persistent connections and **won't work** in serverless mode:
 >
 > - **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.).
 
@@ -443,8 +424,6 @@ 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.
@@ -797,144 +776,6 @@ 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).
@@ -1561,7 +1402,9 @@ 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. 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.
+
+> **Note:** Visit [MCP Apps](https://mastra.ai/docs/mcp/mcp-apps) for the full app bridge API and usage patterns.
 
 ## Related information