@mastra/mcp-docs-server 1.0.0-beta.10 → 1.0.0-beta.13

package/.docs/raw/reference/streaming/agents/stream.mdx

@@ -12,13 +12,7 @@ The `.stream()` method enables real-time streaming of responses from an agent wi
 ## Usage example
 
 ```ts title="index.ts" copy
-// Default Mastra format
-const mastraStream = await agent.stream("message for agent");
-
-// AI SDK v5 compatible format
-const aiSdkStream = await agent.stream("message for agent", {
-  format: "aisdk",
-});
+const stream = await agent.stream("message for agent");
 ```
 
 :::info
@@ -50,14 +44,6 @@ const aiSdkStream = await agent.stream("message for agent", {
 
 <PropertiesTable
   content={[
-    {
-      name: "format",
-      type: "'mastra' | 'aisdk'",
-      isOptional: true,
-      defaultValue: "'mastra'",
-      description:
-        "Determines the output stream format. Use 'mastra' for Mastra's native format (default) or 'aisdk' for AI SDK v5 compatibility.",
-    },
     {
       name: "maxSteps",
       type: "number",
@@ -491,6 +477,27 @@ const aiSdkStream = await agent.stream("message for agent", {
       description:
         "Save messages incrementally after each stream step completes (default: false).",
     },
+    {
+      name: "requireToolApproval",
+      type: "boolean",
+      isOptional: true,
+      description:
+        "When true, all tool calls require explicit approval before execution. The stream will emit `tool-call-approval` chunks and pause until `approveToolCall()` or `declineToolCall()` is called.",
+    },
+    {
+      name: "autoResumeSuspendedTools",
+      type: "boolean",
+      isOptional: true,
+      description:
+        "When true, automatically resumes suspended tools when the user sends a new message on the same thread. The agent extracts `resumeData` from the user's message based on the tool's `resumeSchema`. Requires memory to be configured.",
+    },
+    {
+      name: "toolCallConcurrency",
+      type: "number",
+      isOptional: true,
+      description:
+        "Maximum number of tool calls to execute concurrently. Defaults to 1 when approval may be required, otherwise 10.",
+    },
     {
       name: "providerOptions",
       type: "Record<string, Record<string, JSONValue>>",
@@ -650,9 +657,9 @@ const aiSdkStream = await agent.stream("message for agent", {
   content={[
     {
       name: "stream",
-      type: "MastraModelOutput<Output> | AISDKV5OutputStream<Output>",
+      type: "MastraModelOutput<Output>",
       description:
-        "Returns a streaming interface based on the format parameter. When format is 'mastra' (default), returns MastraModelOutput. When format is 'aisdk', returns AISDKV5OutputStream for AI SDK v5 compatibility.",
+        "Returns a MastraModelOutput instance that provides access to the streaming output.",
     },
     {
       name: "traceId",
@@ -683,32 +690,34 @@ for await (const chunk of stream.textStream) {
   console.log(chunk);
 }
 
+// or access full stream
+for await (const chunk of stream.fullStream) {
+  console.log(chunk);
+}
+
 // Get full text after streaming
 const fullText = await stream.text;
 ```
 
 ### AI SDK v5 Format
 
+To use the stream with AI SDK v5, you can convert it using our utility function `toAISdkStream`.
+
 ```ts title="index.ts" showLineNumbers copy
-import { stepCountIs } from "ai-v5";
+import { stepCountIs, createUIMessageStreamResponse } from "ai";
+import { toAISdkStream } from "@mastra/ai-sdk";
 
 const stream = await agent.stream("Tell me a story", {
-  format: "aisdk",
   stopWhen: stepCountIs(3), // Stop after 3 steps
   modelSettings: {
     temperature: 0.7,
   },
 });
 
-// Use with AI SDK v5 compatible interfaces
-for await (const part of stream.fullStream) {
-  if (part.type === "text-delta") {
-    console.log(part.text);
-  }
-}
-
 // In an API route for frontend integration
-return stream.toUIMessageStreamResponse();
+return createUIMessageStreamResponse({
+  stream: toAISdkStream(stream, { from: "agent" }),
+})
 ```
 
 ### Using Callbacks
@@ -744,10 +753,9 @@ for await (const chunk of stream.textStream) {
 
 ```ts title="index.ts" showLineNumbers copy
 import { z } from "zod";
-import { stepCountIs } from "ai-v5";
+import { stepCountIs } from "ai";
 
 await agent.stream("message for agent", {
-  format: "aisdk", // Enable AI SDK v5 compatibility
   stopWhen: stepCountIs(3), // Stop after 3 steps
   modelSettings: {
     temperature: 0.7,
@@ -778,3 +786,4 @@ await agent.stream("message for agent", {
 
 - [Generating responses](/docs/v1/agents/overview#generating-responses)
 - [Streaming responses](/docs/v1/agents/overview#generating-responses)
+- [Agent Approval](/docs/v1/agents/agent-approval)

package/.docs/raw/reference/streaming/workflows/stream.mdx

@@ -5,18 +5,22 @@ description: Documentation for the `Run.stream()` method in workflows, which ena
 
 # Run.stream()
 
-The `.stream()` method enables real-time streaming of responses from a workflow.
+The `.stream()` method enables real-time streaming of responses from a workflow. It returns a `ReadableStream` of events directly.
 
 ## Usage example
 
 ```typescript showLineNumbers copy
 const run = await workflow.createRun();
 
-const stream = run.stream({
+const stream = await run.stream({
   inputData: {
     value: "initial data",
   },
 });
+
+for await (const chunk of stream) {
+  console.log(chunk);
+}
 ```
 
 ## Parameters
@@ -129,35 +133,30 @@ const stream = run.stream({
 
 ## Returns
 
+Returns a `WorkflowRunOutput` object that implements the async iterable interface (can be used directly in `for await...of` loops) and provides access to the stream and workflow execution results.
+
 <PropertiesTable
   content={[
     {
-      name: "stream",
-      type: "MastraWorkflowStream<ChunkType>",
+      name: "fullStream",
+      type: "ReadableStream<WorkflowStreamEvent>",
       description:
-        "A custom stream that extends ReadableStream<ChunkType> with additional workflow-specific properties",
+        "A ReadableStream of workflow events that you can iterate over to track progress in real-time. You can also iterate over the WorkflowRunOutput object directly.",
     },
     {
-      name: "stream.status",
-      type: "Promise<RunStatus>",
-      description: "A promise that resolves to the current workflow run status",
-    },
-    {
-      name: "stream.result",
-      type: "Promise<WorkflowResult<TState, TOutput, TSteps>>",
+      name: "result",
+      type: "Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>",
       description: "A promise that resolves to the final workflow result",
     },
     {
-      name: "stream.usage",
-      type: "Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cacheInputTokens?: number }>",
-      description: "A promise that resolves to token usage statistics",
+      name: "status",
+      type: "WorkflowRunStatus",
+      description: "The current workflow run status ('running', 'suspended', 'success', 'failed', 'canceled', or 'tripwire')",
     },
     {
-      name: "stream.traceId",
-      type: "string",
-      isOptional: true,
-      description:
-        "The trace ID associated with this execution when Tracing is enabled.",
+      name: "usage",
+      type: "Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cachedInputTokens?: number }>",
+      description: "A promise that resolves to token usage statistics",
     },
   ]}
 />
@@ -173,7 +172,21 @@ const stream = run.stream({
   },
 });
 
+// Iterate over stream events (you can iterate over stream directly or use stream.fullStream)
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+
+// Access the final result
 const result = await stream.result;
+console.log("Final result:", result);
+
+// Access token usage
+const usage = await stream.usage;
+console.log("Token usage:", usage);
+
+// Check current status
+console.log("Status:", stream.status);
 ```
 
 ## Stream Events

package/.docs/raw/reference/tools/create-tool.mdx

@@ -63,6 +63,27 @@ export const tool = createTool({
         "A Zod schema defining the expected output structure of the tool's `execute` function.",
       isOptional: true,
     },
+    {
+      name: "suspendSchema",
+      type: "Zod schema",
+      description:
+        "A Zod schema defining the structure of the payload passed to `suspend()`. This payload is returned to the client when the tool suspends execution.",
+      isOptional: true,
+    },
+    {
+      name: "resumeSchema",
+      type: "Zod schema",
+      description:
+        "A Zod schema defining the expected structure of `resumeData` when the tool is resumed. Used by the agent to extract data from user messages when `autoResumeSuspendedTools` is enabled.",
+      isOptional: true,
+    },
+    {
+      name: "requireApproval",
+      type: "boolean",
+      description:
+        "When true, the tool requires explicit approval before execution. The agent will emit a `tool-call-approval` chunk and pause until approved or declined.",
+      isOptional: true,
+    },
     {
       name: "execute",
       type: "function",
@@ -284,5 +305,6 @@ Hook errors are caught and logged automatically, but do not prevent tool executi
 
 - [MCP Overview](/docs/v1/mcp/overview)
 - [Using Tools with Agents](/docs/v1/agents/using-tools)
+- [Agent Approval](/docs/v1/agents/agent-approval)
 - [Tool Streaming](/docs/v1/streaming/tool-streaming)
-- [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)
+- [Request Context](/docs/v1/server/request-context#accessing-values-with-tools)

package/.docs/raw/reference/tools/graph-rag-tool.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Reference: createGraphRAGTool() | Tools & MCP"
-description: Documentation for the Graph RAG Tool in Mastra, which enhances RAG by building a graph of semantic relationships between documents.
+description: Documentation for the GraphRAG Tool in Mastra, which enhances RAG by building a graph of semantic relationships between documents.
 ---
 
 # createGraphRAGTool()
@@ -253,8 +253,8 @@ const response = await agent.generate(
 
 For more information on request context, please see:
 
-- [Agent Request Context](/docs/v1/server-db/request-context)
-- [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)
+- [Agent Request Context](/docs/v1/server/request-context)
+- [Request Context](/docs/v1/server/request-context#accessing-values-with-tools)
 
 ## Related
 

package/.docs/raw/reference/tools/vector-query-tool.mdx

@@ -326,7 +326,7 @@ This agent-driven approach:
 
 For detailed filter syntax and store-specific capabilities, see the [Metadata Filters](../rag/metadata-filters) documentation.
 
-For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](/examples/v1/rag/usage/filter-rag) example.
+For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/filter-rag) example.
 
 ## Example with Reranking
 
@@ -567,8 +567,8 @@ const response = await agent.generate(
 
 For more information on request context, please see:
 
-- [Agent Request Context](/docs/v1/server-db/request-context)
-- [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)
+- [Agent Request Context](/docs/v1/server/request-context)
+- [Request Context](/docs/v1/server/request-context#accessing-values-with-tools)
 
 ## Usage Without a Mastra Server
 

package/.docs/raw/reference/workflows/run-methods/startAsync.mdx

@@ -0,0 +1,143 @@
+---
+title: "Reference: Run.startAsync() | Workflows"
+description: Documentation for the `Run.startAsync()` method in workflows, which starts a workflow run without waiting for completion (fire-and-forget).
+---
+
+# Run.startAsync()
+
+The `.startAsync()` method starts a workflow run without waiting for completion. It returns immediately with the `runId`, allowing the workflow to execute in the background. This is useful for long-running workflows, scheduled tasks, or when you want to avoid blocking on workflow completion.
+
+## Usage example
+
+```typescript showLineNumbers copy
+const run = await workflow.createRun();
+
+// Fire-and-forget - returns immediately
+const { runId } = await run.startAsync({
+  inputData: {
+    value: "initial data",
+  },
+});
+
+// Optionally poll for completion later
+const result = await workflow.getWorkflowRunExecutionResult(runId);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "inputData",
+      type: "z.infer<TInput>",
+      description: "Input data that matches the workflow's input schema",
+      isOptional: true,
+    },
+    {
+      name: "requestContext",
+      type: "RequestContext",
+      description: "Request Context data to use during workflow execution",
+      isOptional: true,
+    },
+    {
+      name: "initialState",
+      type: "z.infer<TState>",
+      description: "Initial state to use for the workflow execution",
+      isOptional: true,
+    },
+    {
+      name: "tracingOptions",
+      type: "TracingOptions",
+      isOptional: true,
+      description: "Options for Tracing configuration.",
+      properties: [
+        {
+          parameters: [
+            {
+              name: "metadata",
+              type: "Record<string, any>",
+              isOptional: true,
+              description:
+                "Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "traceId",
+              type: "string",
+              isOptional: true,
+              description:
+                "Trace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "outputOptions",
+      type: "OutputOptions",
+      isOptional: true,
+      description: "Options for output configuration.",
+      properties: [
+        {
+          parameters: [
+            {
+              name: "includeState",
+              type: "boolean",
+              isOptional: true,
+              description:
+                "Whether to include the workflow run state in the result.",
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "runId",
+      type: "string",
+      description:
+        "The unique identifier for this workflow run. Use this to check status or retrieve results later.",
+    },
+  ]}
+/>
+
+## When to use startAsync()
+
+Use `startAsync()` instead of `start()` when:
+
+- **Long-running workflows**: The workflow may take minutes or hours to complete
+- **Scheduled/cron triggers**: You want to trigger a workflow without blocking the scheduler
+- **Avoiding polling failures**: With Inngest workflows, `start()` polls for completion which can fail and cause retries. `startAsync()` avoids this issue
+- **Background processing**: You want to queue work and handle results asynchronously
+
+## Checking workflow status
+
+After calling `startAsync()`, you can check the workflow status using:
+
+```typescript showLineNumbers copy
+// Get the execution result (including step outputs)
+const result = await workflow.getWorkflowRunExecutionResult(runId);
+
+if (result?.status === 'success') {
+  console.log('Workflow completed:', result.steps);
+} else if (result?.status === 'failed') {
+  console.log('Workflow failed:', result.error);
+} else if (result?.status === 'running') {
+  console.log('Workflow still running...');
+}
+```
+
+## Related
+
+- [Run.start()](./start) - Start a workflow and wait for completion
+- [Workflows overview](/docs/v1/workflows/overview)
+- [Workflow.createRun()](../workflow-methods/create-run)

package/.docs/raw/reference/workflows/workflow-methods/create-run.mdx

@@ -23,6 +23,18 @@ await workflow.createRun();
       description: "Optional custom identifier for the workflow run",
       isOptional: true,
     },
+    {
+      name: "resourceId",
+      type: "string",
+      description: "Optional identifier to associate the workflow run with a specific resource (e.g., user ID, tenant ID). This value is persisted with the workflow run and can be used for filtering and querying runs.",
+      isOptional: true,
+    },
+    {
+      name: "disableScorers",
+      type: "boolean",
+      description: "Optional flag to disable scorers for this workflow run",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -53,6 +65,29 @@ const result = await run.start({
 });
 ```
 
+## Using resourceId
+
+The `resourceId` parameter associates a workflow run with a specific resource, such as a user or tenant. This is useful for multi-tenant applications or when you need to track which user initiated a workflow.
+
+```typescript showLineNumbers copy
+const workflow = mastra.getWorkflow("workflow");
+
+// Create a run associated with a specific user
+const run = await workflow.createRun({
+  resourceId: "user-123",
+});
+
+const result = await run.start({
+  inputData: {
+    value: 10,
+  },
+});
+
+// Later, retrieve the run and access the resourceId
+const storedRun = await workflow.getWorkflowRunById(run.runId);
+console.log(storedRun.resourceId); // "user-123"
+```
+
 ## Related
 
 - [Run Class](../run)

package/.docs/raw/reference/workflows/workflow-methods/foreach.mdx

@@ -5,7 +5,7 @@ description: Documentation for the `Workflow.foreach()` method in workflows, whi
 
 # Workflow.foreach()
 
-The `.foreach()` method creates a loop that executes a step for each item in an array.
+The `.foreach()` method creates a loop that executes a step for each item in an array. It always returns an array containing the output from each iteration, preserving the original order.
 
 ## Usage example
 
@@ -50,11 +50,76 @@ workflow.foreach(step1, { concurrency: 2 });
     {
       name: "workflow",
       type: "Workflow",
-      description: "The workflow instance for method chaining",
+      description: "The workflow instance for method chaining. The output type is an array of the step's output type.",
     },
   ]}
 />
 
+## Behavior
+
+### Execution and waiting
+
+The `.foreach()` method processes all items before the next step executes. The step following `.foreach()` only runs after every iteration has completed, regardless of concurrency settings. With `concurrency: 1` (default), items process sequentially. With higher concurrency, items process in parallel batches, but the next step still waits for all batches to finish.
+
+If you need to run multiple operations per item, use a nested workflow as the step. This keeps all operations for each item together and is cleaner than chaining multiple `.foreach()` calls. See [Nested workflows inside foreach](/docs/v1/workflows/control-flow#nested-workflows-inside-foreach) for examples.
+
+### Output structure
+
+`.foreach()` always outputs an array. Each element in the output array corresponds to the result of processing the element at the same index in the input array.
+
+```typescript copy
+// Input: [{ value: 1 }, { value: 2 }, { value: 3 }]
+// Step adds 10 to each value
+// Output: [{ value: 11 }, { value: 12 }, { value: 13 }]
+```
+
+### Using `.then()` after `.foreach()`
+
+When you chain `.then()` after `.foreach()`, the next step receives the entire output array as its input. This allows you to aggregate or process all results together.
+
+```typescript copy
+workflow
+  .foreach(processItemStep)    // Output: array of processed items
+  .then(aggregateStep)         // Input: the entire array
+  .commit();
+```
+
+### Using `.map()` after `.foreach()`
+
+Use `.map()` to transform the array output before passing it to the next step:
+
+```typescript copy
+workflow
+  .foreach(processItemStep)
+  .map(async ({ inputData }) => ({
+    total: inputData.reduce((sum, item) => sum + item.value, 0),
+    count: inputData.length
+  }))
+  .then(nextStep)
+  .commit();
+```
+
+### Chaining multiple `.foreach()` calls
+
+When you chain `.foreach()` calls, each operates on the array from the previous step:
+
+```typescript copy
+workflow
+  .foreach(stepA)    // If input is [a, b, c], output is [A, B, C]
+  .foreach(stepB)    // Operates on [A, B, C], output is [A', B', C']
+  .commit();
+```
+
+If a step inside `.foreach()` returns an array, the output becomes an array of arrays. Use `.map()` with `.flat()` to flatten:
+
+```typescript copy
+workflow
+  .foreach(chunkStep)           // Output: [[chunk1, chunk2], [chunk3, chunk4]]
+  .map(async ({ inputData }) => inputData.flat())  // Output: [chunk1, chunk2, chunk3, chunk4]
+  .foreach(embedStep)
+  .commit();
+```
+
 ## Related
 
-- [Repeating with foreach](/docs/v1/workflows/control-flow#looping-with-foreach)
+- [Looping with foreach](/docs/v1/workflows/control-flow#looping-with-foreach)

package/.docs/raw/reference/workflows/workflow.mdx

@@ -85,6 +85,20 @@ export const workflow = createWorkflow({
       isOptional: true,
       defaultValue: "() => true",
     },
+    {
+      name: "onFinish",
+      type: "(result: WorkflowFinishCallbackResult) => void | Promise<void>",
+      description:
+        "Callback invoked when workflow completes with any status (success, failed, suspended, tripwire). Receives the workflow result including status, output, error, and step results. Errors thrown in this callback are caught and logged, not propagated.",
+      isOptional: true,
+    },
+    {
+      name: "onError",
+      type: "(errorInfo: WorkflowErrorCallbackInfo) => void | Promise<void>",
+      description:
+        "Callback invoked only when workflow fails (failed or tripwire status). Receives error details and step results. Errors thrown in this callback are caught and logged, not propagated.",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -130,9 +144,32 @@ A workflow's `status` indicates its current execution state. The possible values
       description:
         "Workflow execution is paused waiting for resume, with suspended step information",
     },
+    {
+      name: "tripwire",
+      type: "string",
+      description:
+        "Workflow was terminated by a processor tripwire. This occurs when an agent step within the workflow triggers a tripwire (e.g., content was blocked by a guardrail). The tripwire information is available on the result.",
+    },
   ]}
 />
 
+### Handling tripwire status
+
+When a workflow contains an agent step that triggers a tripwire, the workflow returns with `status: 'tripwire'` and includes tripwire details:
+
+```typescript showLineNumbers copy
+const run = await workflow.createRun();
+const result = await run.start({ inputData: { message: "Hello" } });
+
+if (result.status === "tripwire") {
+  console.log("Workflow terminated by tripwire:", result.tripwire?.reason);
+  console.log("Processor ID:", result.tripwire?.processorId);
+  console.log("Retry requested:", result.tripwire?.retry);
+}
+```
+
+This is distinct from `status: 'failed'` which indicates an unexpected error. A tripwire status means a processor intentionally stopped execution (e.g., for content moderation).
+
 ## Related
 
 - [Step Class](./step)

package/.docs/raw/{auth → server/auth}/auth0.mdx

@@ -170,7 +170,7 @@ export const createMastraClient = (accessToken: string) => {
 
 > **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 
-> See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
+> See [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
 
 ### Making authenticated requests
 

package/.docs/raw/{auth → server/auth}/clerk.mdx

@@ -93,7 +93,7 @@ export const mastraClient = new MastraClient({
 ```
 
 > **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
-> See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
+> See [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
 
 ### Making authenticated requests
 

package/.docs/raw/{auth → server/auth}/firebase.mdx

@@ -190,7 +190,7 @@ export const createMastraClient = (idToken: string) => {
 
 > **Note:** The ID token must be prefixed with `Bearer` in the Authorization header.
 
-> See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
+> See [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
 
 ### Making authenticated requests