@mastra/mcp-docs-server 1.0.0-beta.5 → 1.0.0-beta.7

package/.docs/raw/server-db/server-adapters.mdx

@@ -0,0 +1,286 @@
+---
+title: "Server Adapters | Server & DB"
+description: "Manually configure a Mastra server using Hono or Express adapters."
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Server Adapters
+
+Server adapters let you run Mastra with your own HTTP server instead of using `mastra build`. While `mastra build` generates a standalone server for you, adapters give you full control over the server setup, letting you integrate Mastra into any Node.js application.
+
+Use adapters when you need to:
+
+- **Integrate Mastra into an existing application** - Add Mastra endpoints to an Express or Hono app you already have running
+- **Control middleware ordering** - Insert your own middleware before or after Mastra's authentication and routing
+- **Deploy to platforms requiring specific server setup** - Some platforms like Cloudflare Workers or custom Docker setups need direct access to the server instance
+- **Use Express instead of Hono** - `mastra build` uses Hono internally, but you may prefer Express for its ecosystem or team familiarity
+
+:::info
+
+For simple deployments without custom server requirements, use `mastra build` instead. It configures server setup, registers middleware, and applies deployment settings based on your project configuration. See [Server Configuration](/docs/v1/server-db/mastra-server).
+
+:::
+
+## Available adapters
+
+- **[@mastra/hono](/reference/v1/server/hono-adapter)** - Hono framework adapter
+- **[@mastra/express](/reference/v1/server/express-adapter)** - Express framework adapter
+
+## Basic setup
+
+Both adapters follow the same pattern. The adapter wraps your framework's app instance and registers Mastra's routes and middleware onto it.
+
+1. **Create your framework's app instance** - Initialize Hono or Express as you normally would
+2. **Create a `MastraServer`** - Pass your app and Mastra instance to the adapter
+3. **Call `init()`** - This registers context middleware, authentication, and all API routes
+
+After `init()`, your app has all the Mastra endpoints (`/api/agents`, `/api/workflows`, etc.) and you can add your own routes before or after.
+
+See the [Hono Adapter](/reference/v1/server/hono-adapter) or [Express Adapter](/reference/v1/server/express-adapter) docs for framework-specific setup and code examples.
+
+## Constructor options
+
+Both adapters accept the same options:
+
+<PropertiesTable
+  content={[
+    {
+      name: "app",
+      type: "Hono | Application",
+      description: "Framework app instance",
+      isOptional: false,
+    },
+    {
+      name: "mastra",
+      type: "Mastra",
+      description: "Mastra instance",
+      isOptional: false,
+    },
+    {
+      name: "prefix",
+      type: "string",
+      description: "Route path prefix (e.g., `/api/v2`)",
+      isOptional: true,
+      defaultValue: "''",
+    },
+    {
+      name: "openapiPath",
+      type: "string",
+      description: "Path to serve OpenAPI spec (e.g., `/openapi.json`)",
+      isOptional: true,
+    },
+    {
+      name: "bodyLimitOptions",
+      type: "{ maxSize: number, onError: (err) => unknown }",
+      description: "Request body size limits",
+      isOptional: true,
+    },
+    {
+      name: "streamOptions",
+      type: "{ redact?: boolean }",
+      description: "Stream redaction config. When true, redacts sensitive data from streams.",
+      isOptional: true,
+      defaultValue: "{ redact: true }",
+    },
+    {
+      name: "customRouteAuthConfig",
+      type: "Map<string, boolean>",
+      description: "Per-route auth overrides. Keys are `METHOD:PATH` (e.g., `GET:/api/health`). Value `false` makes route public, `true` requires auth.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Initialization flow
+
+Calling `init()` runs three steps in order. Understanding this flow helps when you need to insert your own middleware at specific points.
+
+1. **`registerContextMiddleware()`** - Attaches the Mastra instance, request context, tools, and abort signal to every request. This makes Mastra available to all subsequent middleware and route handlers.
+2. **`registerAuthMiddleware()`** - Adds authentication and authorization middleware, but only if `server.auth` is configured in your Mastra instance. Skipped entirely if no auth is configured.
+3. **`registerRoutes()`** - Registers all Mastra API routes for agents, workflows, and other features. Also registers MCP routes if MCP servers are configured.
+
+### Manual initialization
+
+For custom middleware ordering, call each method separately instead of `init()`. This is useful when you need middleware that runs before Mastra's context is set up, or when you need to insert logic between the initialization steps.
+
+```typescript title="server.ts" copy showLineNumbers
+const server = new MastraServer({ app, mastra });
+
+// Your middleware first
+app.use(loggingMiddleware);
+
+server.registerContextMiddleware();
+
+// Middleware that needs Mastra context
+app.use(customMiddleware);
+
+server.registerAuthMiddleware();
+await server.registerRoutes();
+
+// Routes after Mastra
+app.get('/health', ...);
+```
+
+:::tip
+
+Use manual initialization when you need middleware that runs before Mastra's context is available, or when you need to insert middleware between the context and auth steps.
+
+:::
+
+## Adding custom routes
+
+You can add your own routes to the app alongside Mastra's routes. Routes added after `init()` have access to the Mastra context (the Mastra instance, request context, authenticated user, etc.) through framework-specific mechanisms.
+
+The timing matters: routes added before `init()` won't have Mastra context available, while routes added after `init()` will. See the framework-specific docs for syntax and examples:
+
+- [Hono: Adding custom routes](/reference/v1/server/hono-adapter#adding-custom-routes)
+- [Express: Adding custom routes](/reference/v1/server/express-adapter#adding-custom-routes)
+
+## Route prefixes
+
+By default, Mastra routes are registered at `/api/agents`, `/api/workflows`, etc. Use the `prefix` option to change this, which is useful for API versioning or when integrating with an existing app that has its own `/api` routes.
+
+```typescript copy showLineNumbers
+const server = new MastraServer({
+  app,
+  mastra,
+  prefix: '/api/v2',
+});
+```
+
+With this prefix, Mastra routes become `/api/v2/agents`, `/api/v2/workflows`, etc. Custom routes you add directly to the app are not affected by this prefix.
+
+## OpenAPI spec
+
+Mastra can generate an OpenAPI specification for all registered routes. This is useful for documentation, client generation, or integration with API tools. Enable it by setting the `openapiPath` option:
+
+```typescript copy showLineNumbers
+const server = new MastraServer({
+  app,
+  mastra,
+  openapiPath: '/openapi.json',
+});
+```
+
+The spec is generated from the Zod schemas defined on each route and served at the specified path. It includes all Mastra routes as well as any custom routes created with `createRoute()`.
+
+## Stream data redaction
+
+When streaming agent responses over HTTP, the HTTP streaming layer redacts sensitive information from stream chunks before sending them to clients. This prevents accidental exposure of:
+
+- System prompts and agent instructions
+- Tool definitions and their parameters
+- API keys and other credentials in request bodies
+- Internal configuration data
+
+This redaction happens at the HTTP boundary, so internal callbacks like `onStepFinish` still have access to the full request data for debugging and observability purposes.
+
+By default, redaction is enabled. Configure this behavior via `streamOptions`:
+
+```typescript copy showLineNumbers
+const server = new MastraServer({
+  app,
+  mastra,
+  streamOptions: {
+    redact: true, // Default
+  },
+});
+```
+
+Set `redact: false` only for internal services or debugging scenarios where you need access to the full request data in stream responses.
+
+## Per-route auth overrides
+
+When authentication is configured on your Mastra instance, all routes require authentication by default. Sometimes you need exceptions: public health check endpoints, webhook receivers, or admin routes that need stricter controls.
+
+Use `customRouteAuthConfig` to override authentication behavior for specific routes:
+
+```typescript copy showLineNumbers
+const server = new MastraServer({
+  app,
+  mastra,
+  customRouteAuthConfig: new Map([
+    ['GET:/api/health', false],       // Public health check
+    ['GET:/api/openapi.json', false], // Public API spec
+    ['POST:/api/webhooks/*', false],  // Public webhook endpoints
+    ['POST:/api/admin/reset', true],  // Require auth even if globally disabled
+    ['ALL:/api/internal/*', true],    // Protect all methods on internal routes
+  ]),
+});
+```
+
+Keys follow the format `METHOD:PATH` where method is `GET`, `POST`, `PUT`, `DELETE`, or `ALL`. Paths support wildcards (`*`) for matching multiple routes. Setting a value to `false` makes the route public, while `true` requires authentication.
+
+## Accessing the app
+
+After creating the adapter, you may need to access the underlying framework app instance—for example, to pass it to a platform's serve function or to add routes programmatically from another module.
+
+```typescript copy showLineNumbers
+// Via the MastraServer instance
+const app = server.getApp();
+
+// Via the Mastra instance (available after adapter construction)
+const app = mastra.getServerApp();
+```
+
+Both methods return the same app instance. Use whichever is more convenient based on what's in scope.
+
+## Server config vs adapter options
+
+When using server adapters, configuration comes from two places: the Mastra `server` config (passed to the `Mastra` constructor) and the adapter constructor options. Understanding which options come from where helps avoid confusion when settings don't seem to take effect.
+
+### Used by adapters
+
+The adapter reads these settings from `mastra.getServer()`:
+
+| Option | Description |
+|--------|-------------|
+| `auth` | Authentication config, used by `registerAuthMiddleware()`. |
+| `bodySizeLimit` | Default body size limit in bytes. Can be overridden per-adapter via `bodyLimitOptions`. |
+
+### Adapter constructor only
+
+These options are passed directly to the adapter constructor and are not read from the Mastra config:
+
+| Option | Description |
+|--------|-------------|
+| `prefix` | Route path prefix |
+| `openapiPath` | OpenAPI spec endpoint |
+| `bodyLimitOptions` | Body size limit with custom error handler |
+| `streamOptions` | Stream redaction settings |
+| `customRouteAuthConfig` | Per-route auth overrides |
+
+### Not used by adapters
+
+These `server` config options are only used by `mastra build` and have no effect when using adapters directly:
+
+| Option | Used by |
+|--------|---------|
+| `port`, `host` | `mastra dev`, `mastra build` |
+| `cors` | `mastra build` adds CORS middleware |
+| `timeout` | `mastra build` |
+| `apiRoutes` | `registerApiRoute()` for `mastra build` |
+| `middleware` | Middleware config for `mastra build` |
+
+When using adapters, configure these features directly with your framework. For example, add CORS middleware using Hono's or Express's built-in CORS packages, and set the port when calling your framework's listen function.
+
+## MCP support
+
+Server adapters register MCP (Model Context Protocol) routes during `registerRoutes()` when MCP servers are configured in your Mastra instance. MCP allows external tools and services to connect to your Mastra server and interact with your agents.
+
+The adapter registers routes for both HTTP and SSE (Server-Sent Events) transports, enabling different client connection patterns.
+
+See [MCP](/docs/v1/mcp/overview) for configuration details and how to set up MCP servers.
+
+## Related
+
+- [Hono Adapter](/reference/v1/server/hono-adapter) - Hono-specific setup
+- [Express Adapter](/reference/v1/server/express-adapter) - Express-specific setup
+- [Custom Adapters](/docs/v1/server-db/custom-adapters) - Building adapters for other frameworks
+- [Server Configuration](/docs/v1/server-db/mastra-server) - Using `mastra build` instead
+- [Authentication](/docs/v1/auth) - Configuring auth for your server
+- [MastraServer Reference](/reference/v1/server/mastra-server) - Full API reference
+- [createRoute() Reference](/reference/v1/server/create-route) - Creating type-safe custom routes

package/.docs/raw/server-db/storage.mdx

@@ -489,12 +489,23 @@ console.log(result.messages); // MastraDBMessage[]
 console.log(result.total); // Total count
 console.log(result.hasMore); // Whether more pages exist
 
+// Get messages from multiple threads at once
+const multiThreadResult = await mastra
+  .getStorage()
+  .listMessages({
+    threadId: ["thread-1", "thread-2", "thread-3"],
+    page: 0,
+    perPage: 100
+  });
+
 // Get messages by their IDs
 const messages = await mastra
   .getStorage()
   .listMessagesById({ messageIds: messageIdArr });
 ```
 
+The `threadId` parameter accepts either a single thread ID string or an array of thread IDs to query messages from multiple threads in a single request.
+
 All message queries return `MastraDBMessage[]` format. If you need to convert messages to AI SDK formats for UI rendering, use the conversion utilities from `@mastra/ai-sdk/ui`:
 
 ```typescript copy

package/.docs/raw/streaming/overview.mdx

@@ -132,14 +132,14 @@ console.log("Token usage:", await networkStream.usage);
 
 Streaming from a workflow returns a sequence of structured events describing the run lifecycle, rather than incremental text chunks. This event-based format makes it possible to track and respond to workflow progress in real time once a run is created using `.createRun()`.
 
-### Using `Run.streamVNext()`
+### Using `Run.stream()`
 
-This is the experimental API. It returns a `ReadableStream` of events directly.
+The `stream()` method returns a `ReadableStream` of events directly.
 
 ```typescript {3,9} showLineNumbers copy
 const run = await testWorkflow.createRun();
 
-const stream = await run.streamVNext({
+const stream = await run.stream({
   inputData: {
     value: "initial data",
   },
@@ -150,16 +150,16 @@ for await (const chunk of stream) {
 }
 ```
 
-> See Run.streamVNext() method documentation for more information.
+> See [Run.stream()](/reference/v1/streaming/workflows/stream) method documentation for more information.
 
 ### Output from `Run.stream()`
 
-The experimental API event structure includes `runId` and `from` at the top level, making it easier to identify and track workflow runs without digging into the payload.
+The event structure includes `runId` and `from` at the top level, making it easier to identify and track workflow runs without digging into the payload.
 
 ```typescript
 // ...
 {
-  type: 'step-start',
+  type: 'workflow-start',
   runId: '1eeaf01a-d2bf-4e3f-8d1b-027795ccd3df',
   from: 'WORKFLOW',
   payload: {

package/.docs/raw/streaming/tool-streaming.mdx

@@ -162,7 +162,7 @@ For detailed documentation on all lifecycle hooks, see the [createTool() referen
 
 ## Tool using an agent
 
-Pipe an agent's `textStream` to the tool's `writer`. This streams partial output, and Mastra automatically aggregates the agent's usage into the tool run.
+Pipe an agent's `fullStream` to the tool's `writer`. This streams partial output, and Mastra automatically aggregates the agent's usage into the tool run.
 
 ```typescript showLineNumbers copy
 import { createTool } from "@mastra/core/tools";
@@ -176,7 +176,7 @@ export const testTool = createTool({
     const testAgent = context?.mastra?.getAgent("testAgent");
     const stream = await testAgent?.stream(`What is the weather in ${city}?`);
 
-    await stream!.textStream.pipeTo(context?.writer!);
+    await stream!.fullStream.pipeTo(context?.writer!);
 
     return {
       value: await stream!.text,

package/.docs/raw/streaming/workflow-streaming.mdx

@@ -16,12 +16,6 @@ By combining writable workflow streams with agent streaming, you gain fine-grain
 
 ### Using the `writer` argument
 
-:::warning
-
-The writer is only available when using `streamVNext`.
-
-:::
-
 The `writer` argument is passed to a workflow step's `execute` function and can be used to emit custom events, data, or values into the active stream. This enables workflow steps to provide intermediate results or status updates while execution is still in progress.
 
 :::warning
@@ -66,7 +60,7 @@ const testWorkflow = mastra.getWorkflow("testWorkflow");
 
 const run = await testWorkflow.createRun();
 
-const stream = await run.streamVNext({
+const stream = await run.stream({
   inputData: {
     value: "initial data",
   },
@@ -77,8 +71,8 @@ for await (const chunk of stream) {
 }
 
 if (result!.status === "suspended") {
-  // if the workflow is suspended, we can resume it with the resumeStreamVNext method
-  const resumedStream = await run.resumeStreamVNext({
+  // if the workflow is suspended, we can resume it with the resumeStream method
+  const resumedStream = await run.resumeStream({
     resumeData: { value: "resume data" },
   });
 
@@ -90,10 +84,10 @@ if (result!.status === "suspended") {
 
 ### Resuming an interrupted workflow stream
 
-If a workflow stream is closed or interrupted for any reason, you can resume it with the `resumeStreamVNext` method. This will return a new `ReadableStream` that you can use to observe the workflow events.
+If a workflow stream is closed or interrupted for any reason, you can resume it with the `resumeStream` method. This will return a new `ReadableStream` that you can use to observe the workflow events.
 
 ```typescript showLineNumbers copy
-const newStream = await run.resumeStreamVNext();
+const newStream = await run.resumeStream();
 
 for await (const chunk of newStream) {
   console.log(chunk);

package/.docs/raw/workflows/error-handling.mdx

@@ -189,4 +189,5 @@ for await (const chunk of stream.stream) {
 
 - [Control Flow](/docs/v1/workflows/control-flow)
 - [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
+- [Time Travel](/docs/v1/workflows/time-travel)
 - [Human-in-the-loop](/docs/v1/workflows/human-in-the-loop)

package/.docs/raw/workflows/human-in-the-loop.mdx

@@ -11,7 +11,7 @@ Some workflows need to pause for human input before continuing. When a workflow
 
 Human-in-the-loop input works much like [pausing a workflow](/docs/v1/workflows/suspend-and-resume) using `suspend()`. The key difference is that when human input is required, you can return `suspend()` with a payload that provides context or guidance to the user on how to continue.
 
-![Pausing a workflow with suspend()](/img/workflows/workflows-suspend-resume-suspend.jpg)
+![Pausing a workflow with suspend()](/img/workflows/workflows-suspend.jpg)
 
 ```typescript {12-17,22-26} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
@@ -66,7 +66,7 @@ When a workflow is suspended, you can access the payload returned by `suspend()`
 
 ```typescript {12} title="src/test-workflow.ts" showLineNumbers copy
 const workflow = mastra.getWorkflow("testWorkflow");
-const run = await workflow.createRunAsync();
+const run = await workflow.createRun();
 
 const result = await run.start({
   inputData: {
@@ -93,11 +93,11 @@ The data returned by the step can include a reason and help the user understand
 
 As with [restarting a workflow](/docs/v1/workflows/suspend-and-resume#restarting-a-workflow-with-resume), use `resume()` with `resumeData` to continue a workflow after receiving input from a human. The workflow resumes from the step where it was paused.
 
-![Restarting a workflow with resume()](/img/workflows/workflows-suspend-resume-resume.jpg)
+![Restarting a workflow with resume()](/img/workflows/workflows-resume.jpg)
 
 ```typescript {13} showLineNumbers copy
 const workflow = mastra.getWorkflow("testWorkflow");
-const run = await workflow.createRunAsync();
+const run = await workflow.createRun();
 
 await run.start({
   inputData: {

package/.docs/raw/workflows/overview.mdx

@@ -90,60 +90,28 @@ Workflows can be composed using a number of different methods. The method you ch
 
 ## Workflow state
 
-Workflow state lets you share values across steps without passing them through every step’s inputSchema and outputSchema. All state values are defined in the workflow’s stateSchema, but each step only declares the values it needs. To set initial values, use initialState when running the workflow.
+Workflow state lets you share values across steps without passing them through every step's inputSchema and outputSchema. Use state for tracking progress, accumulating results, or sharing configuration across the entire workflow.
 
 ```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 const step1 = createStep({
-  // ...
-  stateSchema: z.object({
-    processedItems: z.array(z.string()),
-  }),
+  id: "step-1",
+  inputSchema: z.object({ message: z.string() }),
+  outputSchema: z.object({ formatted: z.string() }),
+  stateSchema: z.object({ counter: z.number() }),
   execute: async ({ inputData, state, setState }) => {
-    const { message } = inputData;
-    const { processedItems } = state;
-
-    setState({
-      ...state,
-      processedItems: [...processedItems, "item-1", "item-2"],
-    });
-
-    return {
-      formatted: message.toUpperCase(),
-    };
-  },
-});
+    // Read from state
+    console.log(state.counter);
 
-const step2 = createStep({
-  // ...
-  stateSchema: z.object({
-    metadata: z.object({
-      processedBy: z.string(),
-    }),
-  }),
-  execute: async ({ inputData, state }) => {
-    const { formatted } = inputData;
-    const { metadata } = state;
+    // Update state for subsequent steps
+    setState({ ...state, counter: state.counter + 1 });
 
-    return {
-      emphasized: `${formatted}!! ${metadata.processedBy}`,
-    };
+    return { formatted: inputData.message.toUpperCase() };
   },
 });
-
-export const testWorkflow = createWorkflow({
-  // ...
-  stateSchema: z.object({
-    processedItems: z.array(z.string()),
-    metadata: z.object({
-      processedBy: z.string(),
-    }),
-  }),
-})
-  .then(step1)
-  .then(step2)
-  .commit();
 ```
 
+> See [Workflow State](/docs/v1/workflows/workflow-state) for complete documentation on state schemas, initial state, persistence across suspend/resume, and nested workflows.
+
 ## Workflows as steps
 
 Use a workflow as a step to reuse its logic within a larger composition. Input and output follow the same schema rules described in [Core principles](/docs/v1/workflows/control-flow).
@@ -302,6 +270,49 @@ The workflow output includes the full execution lifecycle, showing the input and
 }
 ```
 
+## Restarting active workflow runs
+
+When a workflow run loses connection to the server, it can be restarted from the last active step. This is useful for long-running workflows that might still be running when the server loses connection. Restarting a workflow run will resume execution from the last active step, and the workflow will continue from there.
+
+### Restarting all active workflow runs of a workflow with `restartAllActiveWorkflowRuns()`
+
+Use `restartAllActiveWorkflowRuns()` to restart all active workflow runs of a workflow. This helps restart all active workflow runs of a workflow, without having to manually loop through each run and restart.
+
+```typescript showLineNumbers copy
+workflow.restartAllActiveWorkflowRuns();
+```
+
+### Restarting an active workflow run with `restart()`
+
+Use `restart()` to restart an active workflow run from the last active step. This will resume execution from the last active step, and the workflow will continue from there.
+
+```typescript showLineNumbers copy
+const run = await workflow.createRun();
+
+const result = await run.start({ inputData: { value: "initial data" } });
+
+//.. server connection lost,
+
+const restartedResult = await run.restart();
+```
+
+### Identifying active workflow runs
+
+When a workflow run is active, it will have a `status` of `running` or `waiting`. You can check the workflow's `status` to confirm it's active, and use `active` to identify the active workflow run.
+
+```typescript showLineNumbers copy
+const activeRuns = await workflow.listActiveWorkflowRuns();
+if (activeRuns.runs.length > 0) {
+  console.log(activeRuns.runs);
+}
+```
+
+:::Note
+
+When running the local mastra server, all active workflow runs will be restarted automatically when the server starts.
+
+:::
+
 ## Using `RequestContext`
 
 Use [RequestContext](/docs/v1/server-db/request-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
@@ -335,6 +346,7 @@ Use [Studio](/docs/v1/getting-started/studio) to easily run workflows with diffe
 
 For a closer look at workflows, see our [Workflow Guide](/guides/v1/guide/ai-recruiter), which walks through the core concepts with a practical example.
 
+- [Workflow State](/docs/v1/workflows/workflow-state)
 - [Control Flow](/docs/v1/workflows/control-flow)
 - [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
 - [Error Handling](/docs/v1/workflows/error-handling)

package/.docs/raw/workflows/snapshots.mdx

@@ -268,4 +268,5 @@ if (result.status === "suspended") {
 
 - [Control Flow](/docs/v1/workflows/control-flow)
 - [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
+- [Time Travel](/docs/v1/workflows/time-travel)
 - [Human-in-the-loop](/docs/v1/workflows/human-in-the-loop)