@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.1

package/.docs/raw/reference/agents/generate.mdx

@@ -1,24 +1,21 @@
 ---
 title: "Reference: Agent.generate() | Agents"
 description: "Documentation for the `Agent.generate()` method in Mastra agents, which enables non-streaming generation of responses with enhanced capabilities."
+packages:
+  - "@mastra/core"
 ---
 
 import { MODEL_SETTINGS_OBJECT } from "@site/src/components/ModelSettingsProperties";
 
 # Agent.generate()
 
-The `.generate()` method enables non-streaming response generation from an agent, with enhanced capabilities and flexible output formats. It accepts messages and optional generation options, supporting both Mastra’s native format and AI SDK v5 compatibility.
+The `.generate()` method enables non-streaming response generation from an agent with enhanced capabilities. It accepts messages and optional generation options.
 
 ## Usage example
 
-```typescript copy
-// Default Mastra format
-const mastraResult = await agent.generate("message for agent");
-
-// AI SDK v5 compatible format
-const aiSdkResult = await agent.generate("message for agent", {
-  format: "aisdk",
-});
+```typescript
+// Basic usage
+const result = await agent.generate("message for agent");
 
 // With model settings (e.g., limiting output tokens)
 const limitedResult = await agent.generate("Write a short poem about coding", {
@@ -27,11 +24,29 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
     temperature: 0.7,
   },
 });
+
+// With structured output
+const structuredResult = await agent.generate("Extract the user's name and age", {
+  structuredOutput: {
+    schema: z.object({
+      name: z.string(),
+      age: z.number(),
+    }),
+  },
+});
+
+// With memory for conversation persistence
+const memoryResult = await agent.generate("Remember my favorite color is blue", {
+  memory: {
+    thread: "user-123-thread",
+    resource: "user-123",
+  },
+});
 ```
 
 :::info
 
-**Model Compatibility**: This method is designed for V2 models. V1 models should use the [`.generateLegacy()`](./generateLegacy) method. The framework automatically detects your model version and will throw an error if there's a mismatch.
+**Model Compatibility**: This method requires AI SDK v5+ models. If you're using AI SDK v4 models, use the [`.generateLegacy()`](./generateLegacy) method instead. The framework automatically detects your model version and will throw an error if there's a mismatch.
 
 :::
 
@@ -58,20 +73,18 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
 
 <PropertiesTable
   content={[
-    {
-      name: "format",
-      type: "'mastra' | 'aisdk'",
-      isOptional: true,
-      defaultValue: "'mastra'",
-      description:
-        "Determines the output format. Use 'mastra' for Mastra's native format (default) or 'aisdk' for AI SDK v5 compatibility.",
-    },
     {
       name: "maxSteps",
       type: "number",
       isOptional: true,
       description: "Maximum number of steps to run during execution.",
     },
+    {
+      name: "stopWhen",
+      type: "LoopOptions['stopWhen']",
+      isOptional: true,
+      description: "Conditions for stopping execution (e.g., step count, token limit).",
+    },
     {
       name: "scorers",
       type: "MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>",
@@ -165,11 +178,29 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
     },
     {
       name: "prepareStep",
-      type: "PrepareStepFunction<any>",
+      type: "PrepareStepFunction",
       isOptional: true,
       description:
         "Callback function called before each step of multi-step execution.",
     },
+    {
+      name: "requireToolApproval",
+      type: "boolean",
+      isOptional: true,
+      description: "When true, all tool calls require explicit approval before execution. The generate() method will return with `finishReason: 'suspended'` and include a `suspendPayload` with tool call details (`toolCallId`, `toolName`, `args`). Use `approveToolCallGenerate()` or `declineToolCallGenerate()` to proceed. See [Agent Approval](/docs/agents/agent-approval#tool-approval-with-generate) for details.",
+    },
+    {
+      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: "context",
       type: "ModelMessage[]",
@@ -247,6 +278,17 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
             },
           ],
         },
+        {
+          parameters: [
+            {
+              name: "logger",
+              type: "IMastraLogger",
+              isOptional: true,
+              description:
+                "Optional logger instance for structured logging during output generation.",
+            },
+          ],
+        },
         {
           parameters: [
             {
@@ -262,24 +304,31 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
     },
     {
       name: "outputProcessors",
-      type: "Processor[]",
+      type: "OutputProcessorOrWorkflow[]",
       isOptional: true,
       description:
         "Output processors to use for this execution (overrides agent's default).",
     },
+    {
+      name: "maxProcessorRetries",
+      type: "number",
+      isOptional: true,
+      description:
+        "Maximum number of times processors can trigger a retry for this generation. Overrides agent's default maxProcessorRetries.",
+    },
     {
       name: "inputProcessors",
-      type: "Processor[]",
+      type: "InputProcessorOrWorkflow[]",
       isOptional: true,
       description:
         "Input processors to use for this execution (overrides agent's default).",
     },
     {
       name: "instructions",
-      type: "string",
+      type: "string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]",
       isOptional: true,
       description:
-        "Custom instructions that override the agent's default instructions for this execution.",
+        "Custom instructions that override the agent's default instructions for this execution. Can be a single string, message object, or array of either.",
     },
     {
       name: "system",
@@ -331,7 +380,7 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
               type: "MemoryConfig",
               isOptional: true,
               description:
-                "Additional memory configuration options for conversation management.",
+                "Additional memory configuration options including lastMessages, readOnly, semanticRecall, and workingMemory.",
             },
           ],
         },
@@ -339,24 +388,17 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
     },
     {
       name: "onFinish",
-      type: "StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>",
+      type: "LoopConfig['onFinish']",
       isOptional: true,
       description:
-        "Callback fired when generation completes. Type varies by format.",
+        "Callback fired when generation completes.",
     },
     {
       name: "onStepFinish",
-      type: "StreamTextOnStepFinishCallback<any> | never",
+      type: "LoopConfig['onStepFinish']",
       isOptional: true,
       description:
-        "Callback fired after each generation step. Type varies by format.",
-    },
-    {
-      name: "resourceId",
-      type: "string",
-      isOptional: true,
-      description:
-        "Deprecated. Use memory.resource instead. Identifier for the resource/user.",
+        "Callback fired after each generation step.",
     },
     {
       name: "telemetry",
@@ -408,13 +450,6 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
       ],
     },
     MODEL_SETTINGS_OBJECT,
-    {
-      name: "threadId",
-      type: "string",
-      isOptional: true,
-      description:
-        "Deprecated. Use memory.thread instead. Thread identifier for conversation continuity.",
-    },
     {
       name: "toolChoice",
       type: "'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }",
@@ -627,6 +662,13 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
         },
       ],
     },
+    {
+      name: "includeRawChunks",
+      type: "boolean",
+      isOptional: true,
+      description:
+        "Whether to include raw chunks in the stream output. Not available on all model providers.",
+    },
   ]}
 />
 
@@ -636,9 +678,95 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
   content={[
     {
       name: "result",
-      type: "Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>> | Awaited<ReturnType<AISDKV5OutputStream<Output>['getFullOutput']>>",
+      type: "Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>>",
+      description:
+        "Returns the full output of the generation process including text, object (if structured output), tool calls, tool results, usage statistics, and step information.",
+    },
+    {
+      name: "text",
+      type: "string",
+      description:
+        "The generated text response from the agent.",
+    },
+    {
+      name: "object",
+      type: "Output | undefined",
+      isOptional: true,
+      description:
+        "The structured output object if structuredOutput was provided, validated against the schema.",
+    },
+    {
+      name: "toolCalls",
+      type: "ToolCall[]",
+      description:
+        "Array of tool calls made during generation.",
+    },
+    {
+      name: "toolResults",
+      type: "ToolResult[]",
+      description:
+        "Array of results from tool executions.",
+    },
+    {
+      name: "usage",
+      type: "TokenUsage",
+      description:
+        "Token usage statistics for the generation.",
+    },
+    {
+      name: "steps",
+      type: "Step[]",
+      description:
+        "Array of execution steps, useful for debugging multi-step generations.",
+    },
+    {
+      name: "finishReason",
+      type: "string",
+      description:
+        "The reason generation finished. Values include 'stop' (normal completion), 'tool-calls' (ended with tool calls), 'suspended' (waiting for tool approval), or 'error' (error occurred).",
+    },
+    {
+      name: "suspendPayload",
+      type: "object",
+      isOptional: true,
+      description:
+        "Present when `finishReason` is 'suspended'. Contains tool call details needed to approve or decline the pending tool call.",
+      properties: [
+        {
+          parameters: [
+            {
+              name: "toolCallId",
+              type: "string",
+              description: "Unique identifier for the pending tool call.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "toolName",
+              type: "string",
+              description: "Name of the tool that requires approval.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "args",
+              type: "Record<string, any>",
+              description: "Arguments that will be passed to the tool.",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "runId",
+      type: "string",
+      isOptional: true,
       description:
-        "Returns the full output of the generation process. When format is 'mastra' (default), returns MastraModelOutput result. When format is 'aisdk', returns AISDKV5OutputStream result for AI SDK v5 compatibility.",
+        "Unique identifier for this execution run. Required when calling `approveToolCallGenerate()` or `declineToolCallGenerate()` to resume a suspended execution.",
     },
     {
       name: "traceId",

package/.docs/raw/reference/agents/generateLegacy.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.generateLegacy() (Legacy) | Agents"
 description: "Documentation for the legacy `Agent.generateLegacy()` method in Mastra agents. This method is deprecated and will be removed in a future version."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.generateLegacy() (Legacy)
@@ -15,7 +17,7 @@ The `.generateLegacy()` method is the legacy version of the agent generation API
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.generateLegacy("message for agent");
 ```
 
@@ -518,7 +520,7 @@ await agent.generateLegacy("message for agent");
 
 :::info
 
-The new `.generate()` method offers enhanced capabilities including AI SDK v5 compatibility, better structured output handling, and improved streaming support. See the [migration guide](/guides/v1/migrations/vnext-to-standard-apis) for detailed migration instructions.
+The new `.generate()` method offers enhanced capabilities including AI SDK v5+ compatibility, better structured output handling, and improved streaming support. See the [migration guide](/guides/v1/migrations/vnext-to-standard-apis) for detailed migration instructions.
 
 :::
 
@@ -546,7 +548,7 @@ const result = await agent.generate("message", {
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 import { z } from "zod";
 import {
   ModerationProcessor,

package/.docs/raw/reference/agents/getDefaultGenerateOptions.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.getDefaultGenerateOptionsLegacy() | Agents"
 description: "Documentation for the `Agent.getDefaultGenerateOptionsLegacy()` method in Mastra agents, which retrieves the default options used for generateLegacy calls."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.getDefaultGenerateOptionsLegacy()
@@ -15,7 +17,7 @@ Agents can be configured with default generation options for controlling model b
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.getDefaultGenerateOptionsLegacy();
 ```
 
@@ -48,7 +50,7 @@ await agent.getDefaultGenerateOptionsLegacy();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 await agent.getDefaultGenerateOptionsLegacy({
   requestContext: new RequestContext(),
 });
@@ -72,4 +74,4 @@ await agent.getDefaultGenerateOptionsLegacy({
 ## Related
 
 - [Agent generation](/docs/v1/agents/overview#generating-responses)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/reference/agents/getDefaultOptions.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.getDefaultOptions() | Agents"
 description: "Documentation for the `Agent.getDefaultOptions()` method in Mastra agents, which retrieves the default options used for stream and generate calls."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.getDefaultOptions()
@@ -9,7 +11,7 @@ Agents can be configured with default options for memory usage, output format, a
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.getDefaultOptions();
 ```
 
@@ -42,7 +44,7 @@ await agent.getDefaultOptions();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 await agent.getDefaultOptions({
   requestContext: new RequestContext(),
 });
@@ -66,4 +68,4 @@ await agent.getDefaultOptions({
 ## Related
 
 - [Streaming with agents](/docs/v1/streaming/overview#streaming-with-agents)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/reference/agents/getDefaultStreamOptions.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.getDefaultStreamOptionsLegacy() | Agents"
 description: "Documentation for the `Agent.getDefaultStreamOptionsLegacy()` method in Mastra agents, which retrieves the default options used for streamLegacy calls."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.getDefaultStreamOptionsLegacy()
@@ -15,7 +17,7 @@ Agents can be configured with default streaming options for memory usage, output
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.getDefaultStreamOptionsLegacy();
 ```
 
@@ -48,7 +50,7 @@ await agent.getDefaultStreamOptionsLegacy();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 await agent.getDefaultStreamOptionsLegacy({
   requestContext: new RequestContext(),
 });
@@ -72,4 +74,4 @@ await agent.getDefaultStreamOptionsLegacy({
 ## Related
 
 - [Streaming with agents](/docs/v1/streaming/overview#streaming-with-agents)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/reference/agents/getDescription.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.getDescription() | Agents"
 description: "Documentation for the `Agent.getDescription()` method in Mastra agents, which retrieves the agent's description."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.getDescription()
@@ -9,7 +11,7 @@ The `.getDescription()` method retrieves the description configured for an agent
 
 ## Usage example
 
-```typescript copy
+```typescript
 agent.getDescription();
 ```
 

package/.docs/raw/reference/agents/getInstructions.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.getInstructions() | Agents"
 description: "Documentation for the `Agent.getInstructions()` method in Mastra agents, which retrieves the instructions that guide the agent's behavior."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.getInstructions()
@@ -9,7 +11,7 @@ The `.getInstructions()` method retrieves the instructions configured for an age
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.getInstructions();
 ```
 
@@ -42,7 +44,7 @@ await agent.getInstructions();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 await agent.getInstructions({
   requestContext: new RequestContext(),
 });
@@ -66,4 +68,4 @@ await agent.getInstructions({
 ## Related
 
 - [Agents overview](/docs/v1/agents/overview)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/reference/agents/getLLM.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.getLLM() | Agents"
 description: "Documentation for the `Agent.getLLM()` method in Mastra agents, which retrieves the language model instance."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.getLLM()
@@ -9,7 +11,7 @@ The `.getLLM()` method retrieves the language model instance configured for an a
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.getLLM();
 ```
 
@@ -43,7 +45,7 @@ await agent.getLLM();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 await agent.getLLM({
   requestContext: new RequestContext(),
   model: "openai/gpt-5.1",
@@ -75,4 +77,4 @@ await agent.getLLM({
 ## Related
 
 - [Agents overview](/docs/v1/agents/overview)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/reference/agents/getMemory.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.getMemory() | Agents"
 description: "Documentation for the `Agent.getMemory()` method in Mastra agents, which retrieves the memory system associated with the agent."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.getMemory()
@@ -9,7 +11,7 @@ The `.getMemory()` method retrieves the memory system associated with an agent.
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.getMemory();
 ```
 
@@ -42,7 +44,7 @@ await agent.getMemory();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 await agent.getMemory({
   requestContext: new RequestContext(),
 });
@@ -66,4 +68,4 @@ await agent.getMemory({
 ## Related
 
 - [Agent memory](/docs/v1/agents/agent-memory)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/reference/agents/getModel.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.getModel() | Agents"
 description: "Documentation for the `Agent.getModel()` method in Mastra agents, which retrieves the language model that powers the agent."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.getModel()
@@ -9,7 +11,7 @@ The `.getModel()` method retrieves the language model configured for an agent, r
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.getModel();
 ```
 
@@ -42,7 +44,7 @@ await agent.getModel();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 await agent.getModel({
   requestContext: new RequestContext(),
 });
@@ -66,4 +68,4 @@ await agent.getModel({
 ## Related
 
 - [Agents overview](/docs/v1/agents/overview)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/reference/agents/getTools.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.getTools() | Agents"
 description: "Documentation for the `Agent.getTools()` method in Mastra agents, which retrieves the tools that the agent can use."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.getTools()
@@ -9,7 +11,7 @@ The `.getTools()` method retrieves the tools configured for an agent, resolving
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.getTools();
 ```
 
@@ -42,7 +44,7 @@ await agent.getTools();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 await agent.getTools({
   requestContext: new RequestContext(),
 });

package/.docs/raw/reference/agents/getVoice.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.getVoice() | Agents"
 description: "Documentation for the `Agent.getVoice()` method in Mastra agents, which retrieves the voice provider for speech capabilities."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.getVoice()
@@ -9,7 +11,7 @@ The `.getVoice()` method retrieves the voice provider configured for an agent, r
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.getVoice();
 ```
 
@@ -42,7 +44,7 @@ await agent.getVoice();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 await agent.getVoice({
   requestContext: new RequestContext(),
 });