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

package/.docs/raw/reference/storage/postgresql.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: PostgreSQL Storage | Storage | Mastra Docs"
+title: "Reference: PostgreSQL Storage | Storage"
 description: Documentation for the PostgreSQL storage implementation in Mastra.
 ---
 
@@ -101,6 +101,43 @@ The storage implementation handles schema creation and updates automatically. It
 - `mastra_scorers`: Stores scoring and evaluation data
 - `mastra_resources`: Stores resource working memory data
 
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { PostgresStore } from "@mastra/pg";
+
+const storage = new PostgresStore({
+  connectionString: process.env.DATABASE_URL,
+});
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript copy
+import { PostgresStore } from "@mastra/pg";
+
+const storage = new PostgresStore({
+  connectionString: process.env.DATABASE_URL,
+});
+
+// Required when using storage directly
+await storage.init();
+
+// Now you can use the storage
+await storage.getThread({ threadId: "..." });
+```
+
+:::warning
+If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+:::
+
 ### Direct Database and Pool Access
 
 `PostgresStore` exposes both the underlying database object and the pg-promise instance as public fields:

package/.docs/raw/reference/storage/upstash.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Upstash Storage | Storage | Mastra Docs"
+title: "Reference: Upstash Storage | Storage"
 description: Documentation for the Upstash storage implementation in Mastra.
 ---
 

package/.docs/raw/reference/streaming/ChunkType.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: ChunkType | Streaming | Mastra Docs"
+title: "Reference: ChunkType | Streaming"
 description: "Documentation for the ChunkType type used in Mastra streaming responses, defining all possible chunk types and their payloads."
 ---
 
@@ -1325,4 +1325,4 @@ for await (const chunk of stream.fullStream) {
 
 - [.stream()](./agents/stream) - Method that returns streams emitting these chunks
 - [MastraModelOutput](./agents/MastraModelOutput) - The stream object that emits these chunks
-- [workflow.streamVNext()](./workflows/streamVNext) - Method that returns streams emitting these chunks for workflows
+- [workflow.stream()](./workflows/stream) - Method that returns streams emitting these chunks for workflows

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MastraModelOutput | Streaming | Mastra Docs"
+title: "Reference: MastraModelOutput | Streaming"
 description: "Complete reference for MastraModelOutput - the stream object returned by agent.stream() with streaming and promise-based access to model outputs."
 ---
 

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

@@ -1,8 +1,10 @@
 ---
-title: "Reference: Agent.stream() | Streaming | Mastra Docs"
+title: "Reference: Agent.stream() | Streaming"
 description: "Documentation for the `Agent.stream()` method in Mastra agents, which enables real-time streaming of responses with enhanced capabilities."
 ---
 
+import { MODEL_SETTINGS_OBJECT } from "@site/src/components/ModelSettingsProperties";
+
 # Agent.stream()
 
 The `.stream()` method enables real-time streaming of responses from an agent with enhanced capabilities and format flexibility. This method accepts messages and optional streaming options, providing a next-generation streaming experience with support for both Mastra's native format and AI SDK v5 compatibility.
@@ -243,6 +245,17 @@ const aiSdkStream = await agent.stream("message for agent", {
             },
           ],
         },
+        {
+          parameters: [
+            {
+              name: "providerOptions",
+              type: "ProviderOptions",
+              isOptional: true,
+              description:
+                "Provider-specific options passed to the internal structuring agent. Use this to control model behavior like reasoning effort for thinking models (e.g., `{ openai: { reasoningEffort: 'low' } }`).",
+            },
+          ],
+        },
       ],
     },
     {
@@ -252,6 +265,13 @@ const aiSdkStream = await agent.stream("message for agent", {
       description:
         "Overrides the output processors set on the agent. Output processors that can modify or validate messages from the agent before they are returned to the user. Must implement either (or both) of the `processOutputResult` and `processOutputStream` functions.",
     },
+    {
+      name: "includeRawChunks",
+      type: "boolean",
+      isOptional: true,
+      description:
+        "Whether to include raw chunks in the stream output (not available on all model providers).",
+    },
     {
       name: "inputProcessors",
       type: "Processor[]",
@@ -396,91 +416,7 @@ const aiSdkStream = await agent.stream("message for agent", {
         },
       ],
     },
-    {
-      name: "modelSettings",
-      type: "CallSettings",
-      isOptional: true,
-      description:
-        "Model-specific settings like temperature, maxTokens, topP, etc. These are passed to the underlying language model.",
-      properties: [
-        {
-          parameters: [
-            {
-              name: "temperature",
-              type: "number",
-              isOptional: true,
-              description:
-                "Controls randomness in the model's output. Higher values (e.g., 0.8) make the output more random, lower values (e.g., 0.2) make it more focused and deterministic.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "maxRetries",
-              type: "number",
-              isOptional: true,
-              description: "Maximum number of retries for failed requests.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "topP",
-              type: "number",
-              isOptional: true,
-              description:
-                "Nucleus sampling. This is a number between 0 and 1. It is recommended to set either temperature or topP, but not both.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "topK",
-              type: "number",
-              isOptional: true,
-              description:
-                "Only sample from the top K options for each subsequent token. Used to remove 'long tail' low probability responses.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "presencePenalty",
-              type: "number",
-              isOptional: true,
-              description:
-                "Presence penalty setting. It affects the likelihood of the model to repeat information that is already in the prompt. A number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "frequencyPenalty",
-              type: "number",
-              isOptional: true,
-              description:
-                "Frequency penalty setting. It affects the likelihood of the model to repeatedly use the same words or phrases. A number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "stopSequences",
-              type: "string[]",
-              isOptional: true,
-              description:
-                "Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.",
-            },
-          ],
-        },
-      ],
-    },
+    MODEL_SETTINGS_OBJECT,
     {
       name: "threadId",
       type: "string",
@@ -659,15 +595,52 @@ const aiSdkStream = await agent.stream("message for agent", {
             },
           ],
         },
+        {
+          parameters: [
+            {
+              name: "requestContextKeys",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').",
+            },
+          ],
+        },
+        {
+          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.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "parentSpanId",
+              type: "string",
+              isOptional: true,
+              description:
+                "Parent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "tags",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Tags to apply to this trace. String labels for categorizing and filtering traces.",
+            },
+          ],
+        },
       ],
     },
-    {
-      name: "maxTokens",
-      type: "number",
-      isOptional: true,
-      description:
-        "Condition(s) that determine when to stop the agent's execution. Can be a single condition or array of conditions.",
-    },
   ]}
 />
 
@@ -790,12 +763,12 @@ await agent.stream("message for agent", {
       sentiment: z.enum(["positive", "negative", "neutral"]),
       confidence: z.number(),
     }),
-    model: "openai/gpt-4o-mini",
+    model: "openai/gpt-5.1",
     errorStrategy: "warn",
   },
   // Output processors for streaming response validation
   outputProcessors: [
-    new ModerationProcessor({ model: "openai/gpt-4.1-nano" }),
+    new ModerationProcessor({ model: "openrouter/openai/gpt-oss-safeguard-20b" }),
     new BatchPartsProcessor({ maxBatchSize: 3, maxWaitTime: 100 }),
   ],
 });

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.streamLegacy() (Legacy) | Streaming | Mastra Docs"
+title: "Reference: Agent.streamLegacy() (Legacy) | Streaming"
 description: "Documentation for the legacy `Agent.streamLegacy()` method in Mastra agents. This method is deprecated and will be removed in a future version."
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Run.observeStream() | Streaming | Mastra Docs"
+title: "Reference: Run.observeStream() | Streaming"
 description: Documentation for the `Run.observeStream()` method in workflows, which enables reopening the stream of an already active workflow run.
 ---
 
@@ -18,7 +18,7 @@ run.stream({
   },
 });
 
-const { stream } = await run.observeStream();
+const stream = await run.observeStream();
 
 for await (const chunk of stream) {
   console.log(chunk);
@@ -33,17 +33,15 @@ for await (const chunk of stream) {
 
 The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
 
-- **`start`**: Workflow execution begins
-- **`step-start`**: A step begins execution
-- **`tool-call`**: A tool call is initiated
-- **`tool-call-streaming-start`**: Tool call streaming begins
-- **`tool-call-delta`**: Incremental tool output updates
-- **`step-result`**: A step completes with results
-- **`step-finish`**: A step finishes execution
-- **`finish`**: Workflow execution completes
+- **`workflow-start`**: Workflow execution begins
+- **`workflow-step-start`**: A step begins execution
+- **`workflow-step-output`**: Custom output from a step
+- **`workflow-step-result`**: A step completes with results
+- **`workflow-finish`**: Workflow execution completes with usage statistics
 
 ## Related
 
 - [Workflows overview](/docs/v1/workflows/overview#running-workflows)
 - [Workflow.createRun()](/reference/v1/workflows/workflow-methods/create-run)
 - [Run.stream()](./stream)
+- [Run.resumeStream()](./resumeStream)

package/.docs/raw/reference/streaming/workflows/{resumeStreamVNext.mdx → resumeStream.mdx}

@@ -1,22 +1,18 @@
 ---
-title: "Reference: Run.resumeStreamVNext() (Experimental) | Streaming | Mastra Docs"
-description: Documentation for the `Run.resumeStreamVNext()` method in workflows, which enables real-time resumption and streaming of suspended workflow runs.
+title: "Reference: Run.resumeStream() | Streaming"
+description: Documentation for the `Run.resumeStream()` method in workflows, which enables real-time resumption and streaming of suspended workflow runs.
 ---
 
-# Run.resumeStreamVNext() (Experimental)
+# Run.resumeStream()
 
-:::caution Experimental Feature
-This is an experimental API that may change in future versions. The `resumeStreamVNext()` method is part of the enhanced streaming system that will eventually replace the current streaming methods. Use with caution in production environments.
-:::
-
-The `.resumeStreamVNext()` method resumes a suspended workflow run with new data, allowing you to continue execution from a specific step and to observe the stream of events.
+The `.resumeStream()` method resumes a suspended workflow run with new data, allowing you to continue execution from a specific step and to observe the stream of events.
 
 ## Usage example
 
 ```typescript showLineNumbers copy
 const run = await workflow.createRun();
 
-const stream = run.streamVNext({
+const stream = run.stream({
   inputData: {
     value: "initial data",
   },
@@ -25,7 +21,7 @@ const stream = run.streamVNext({
 const result = await stream.result;
 
 if (result!.status === "suspended") {
-  const resumedStream = await run.resumeStreamVNext({
+  const resumedStream = await run.resumeStream({
     resumeData: {
       value: "resume data",
     },
@@ -72,6 +68,50 @@ if (result!.status === "suspended") {
             },
           ],
         },
+        {
+          parameters: [
+            {
+              name: "requestContextKeys",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').",
+            },
+          ],
+        },
+        {
+          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.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "parentSpanId",
+              type: "string",
+              isOptional: true,
+              description:
+                "Parent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "tags",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Tags to apply to this trace. String labels for categorizing and filtering traces.",
+            },
+          ],
+        },
       ],
     },
   ]}
@@ -119,4 +159,4 @@ The stream emits various event types during workflow execution. Each event has a
 
 - [Workflows overview](/docs/v1/workflows/overview#running-workflows)
 - [Workflow.createRun()](/reference/v1/workflows/workflow-methods/create-run)
-- [Run.streamVNext()](./streamVNext)
+- [Run.stream()](./stream)

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

@@ -1,18 +1,18 @@
 ---
-title: "Reference: Run.stream() | Streaming | Mastra Docs"
-description: Documentation for the `Run.stream()` method in workflows, which allows you to monitor the execution of a workflow run as a stream.
+title: "Reference: Run.stream() | Streaming"
+description: Documentation for the `Run.stream()` method in workflows, which enables real-time streaming of responses.
 ---
 
 # Run.stream()
 
-The `.stream()` method allows you to monitor the execution of a workflow run, providing real-time updates on the status of steps.
+The `.stream()` method enables real-time streaming of responses from a workflow.
 
 ## Usage example
 
 ```typescript showLineNumbers copy
 const run = await workflow.createRun();
 
-const { stream } = await run.stream({
+const stream = run.stream({
   inputData: {
     value: "initial data",
   },
@@ -40,7 +40,7 @@ const { stream } = await run.stream({
       type: "TracingContext",
       isOptional: true,
       description:
-        "Tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.",
+        "Tracing context for creating child spans and adding metadata.",
       properties: [
         {
           parameters: [
@@ -49,7 +49,7 @@ const { stream } = await run.stream({
               type: "Span",
               isOptional: true,
               description:
-                "Current span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.",
+                "Current span for creating child spans and adding metadata.",
             },
           ],
         },
@@ -67,13 +67,63 @@ const { stream } = await run.stream({
               name: "metadata",
               type: "Record<string, any>",
               isOptional: true,
+              description: "Metadata to add to the root trace span.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "requestContextKeys",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').",
+            },
+          ],
+        },
+        {
+          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.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "parentSpanId",
+              type: "string",
+              isOptional: true,
               description:
-                "Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.",
+                "Parent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "tags",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Tags to apply to this trace. String labels for categorizing and filtering traces.",
             },
           ],
         },
       ],
     },
+    {
+      name: "closeOnSuspend",
+      type: "boolean",
+      description:
+        "Whether to close the stream when the workflow is suspended, or to keep the stream open until the workflow is finished (by success or error). Default value is true.",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -83,22 +133,31 @@ const { stream } = await run.stream({
   content={[
     {
       name: "stream",
-      type: "ReadableStream<StreamEvent>",
+      type: "MastraWorkflowStream<ChunkType>",
       description:
-        "A readable stream that emits workflow execution events in real-time",
+        "A custom stream that extends ReadableStream<ChunkType> with additional workflow-specific properties",
     },
     {
-      name: "getWorkflowState",
-      type: "() => Promise<WorkflowResult<TState, TOutput, TSteps>>",
-      description:
-        "A function that returns a promise resolving to the final workflow result",
+      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>>",
+      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: "traceId",
+      name: "stream.traceId",
       type: "string",
       isOptional: true,
       description:
-        "The trace ID associated with this execution when Tracing is enabled. Use this to correlate logs and debug execution flow.",
+        "The trace ID associated with this execution when Tracing is enabled.",
     },
   ]}
 />
@@ -106,29 +165,29 @@ const { stream } = await run.stream({
 ## Extended usage example
 
 ```typescript showLineNumbers copy
-const { getWorkflowState } = await run.stream({
+const run = await workflow.createRun();
+
+const stream = run.stream({
   inputData: {
     value: "initial data",
   },
 });
 
-const result = await getWorkflowState();
+const result = await stream.result;
 ```
 
 ## Stream Events
 
 The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
 
-- **`start`**: Workflow execution begins
-- **`step-start`**: A step begins execution
-- **`tool-call`**: A tool call is initiated
-- **`tool-call-streaming-start`**: Tool call streaming begins
-- **`tool-call-delta`**: Incremental tool output updates
-- **`step-result`**: A step completes with results
-- **`step-finish`**: A step finishes execution
-- **`finish`**: Workflow execution completes
+- **`workflow-start`**: Workflow execution begins
+- **`workflow-step-start`**: A step begins execution
+- **`workflow-step-output`**: Custom output from a step
+- **`workflow-step-result`**: A step completes with results
+- **`workflow-finish`**: Workflow execution completes with usage statistics
 
 ## Related
 
 - [Workflows overview](/docs/v1/workflows/overview#running-workflows)
 - [Workflow.createRun()](/reference/v1/workflows/workflow-methods/create-run)
+- [Run.resumeStream()](./resumeStream)