@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.6

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

@@ -1,18 +1,18 @@
 ---
 title: "Reference: Run.stream() | Streaming"
-description: Documentation for the `Run.stream()` method in workflows, which allows you to monitor the execution of a workflow run as a stream.
+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)

package/.docs/raw/reference/templates/overview.mdx

@@ -118,13 +118,10 @@ We recommend using OpenAI, Anthropic, or Google model providers for templates. C
 
 ```typescript title="src/mastra/agents/example-agent.ts"
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-// Or use: import { anthropic } from '@ai-sdk/anthropic';
-// Or use: import { google } from '@ai-sdk/google';
 
 const agent = new Agent({
   name: "example-agent",
-  model: openai("gpt-4"), // or anthropic('') or google('')
+  model: "openai/gpt-5.1", // or other provider strings
   instructions: "Your agent instructions here",
   // ... other configuration
 });

package/.docs/raw/reference/tools/client.mdx

@@ -230,7 +230,6 @@ Returns an object mapping tool names to their corresponding Mastra tool implemen
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { MastraMCPClient } from "@mastra/mcp";
-import { openai } from "@ai-sdk/openai";
 
 // Initialize the MCP client using mcp/fetch as an example https://hub.docker.com/r/mcp/fetch
 // Visit https://github.com/docker/mcp-servers for other reference docker mcp servers
@@ -250,7 +249,7 @@ const agent = new Agent({
   name: "Fetch agent",
   instructions:
     "You are able to fetch data from URLs on demand and discuss the response data with the user.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
 });
 
 try {

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

@@ -131,6 +131,34 @@ export const tool = createTool({
         },
       ],
     },
+    {
+      name: "onInputStart",
+      type: "function",
+      description:
+        "Optional callback invoked when the tool call input streaming begins. Receives `toolCallId`, `messages`, and `abortSignal`.",
+      isOptional: true,
+    },
+    {
+      name: "onInputDelta",
+      type: "function",
+      description:
+        "Optional callback invoked for each incremental chunk of input text as it streams in. Receives `inputTextDelta`, `toolCallId`, `messages`, and `abortSignal`.",
+      isOptional: true,
+    },
+    {
+      name: "onInputAvailable",
+      type: "function",
+      description:
+        "Optional callback invoked when the complete tool input is available and parsed. Receives the validated `input` object, `toolCallId`, `messages`, and `abortSignal`.",
+      isOptional: true,
+    },
+    {
+      name: "onOutput",
+      type: "function",
+      description:
+        "Optional callback invoked after the tool has successfully executed and returned output. Receives the tool's `output`, `toolCallId`, `messages`, and `abortSignal`.",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -149,8 +177,112 @@ The `createTool()` function returns a `Tool` object.
   ]}
 />
 
+## Tool Lifecycle Hooks
+
+Tools support lifecycle hooks that allow you to monitor and react to different stages of tool execution. These hooks are particularly useful for logging, analytics, validation, and real-time updates during streaming.
+
+### Available Hooks
+
+#### onInputStart
+
+Called when tool call input streaming begins, before any input data is received.
+
+```typescript
+export const tool = createTool({
+  id: "example-tool",
+  description: "Example tool with hooks",
+  onInputStart: ({ toolCallId, messages, abortSignal }) => {
+    console.log(`Tool ${toolCallId} input streaming started`);
+  },
+  // ... other properties
+});
+```
+
+#### onInputDelta
+
+Called for each incremental chunk of input text as it streams in. Useful for showing real-time progress or parsing partial JSON.
+
+```typescript
+export const tool = createTool({
+  id: "example-tool",
+  description: "Example tool with hooks",
+  onInputDelta: ({ inputTextDelta, toolCallId, messages, abortSignal }) => {
+    console.log(`Received input chunk: ${inputTextDelta}`);
+  },
+  // ... other properties
+});
+```
+
+#### onInputAvailable
+
+Called when the complete tool input is available and has been parsed and validated against the `inputSchema`.
+
+```typescript
+export const tool = createTool({
+  id: "example-tool",
+  description: "Example tool with hooks",
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  onInputAvailable: ({ input, toolCallId, messages, abortSignal }) => {
+    console.log(`Tool received complete input:`, input);
+    // input is fully typed based on inputSchema
+  },
+  // ... other properties
+});
+```
+
+#### onOutput
+
+Called after the tool has successfully executed and returned output. Useful for logging results, triggering follow-up actions, or analytics.
+
+```typescript
+export const tool = createTool({
+  id: "example-tool",
+  description: "Example tool with hooks",
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  execute: async (input) => {
+    return { result: "Success" };
+  },
+  onOutput: ({ output, toolCallId, toolName, abortSignal }) => {
+    console.log(`${toolName} execution completed:`, output);
+    // output is fully typed based on outputSchema
+  },
+});
+```
+
+### Hook Execution Order
+
+For a typical streaming tool call, the hooks are invoked in this order:
+
+1. **onInputStart** - Input streaming begins
+2. **onInputDelta** - Called multiple times as chunks arrive
+3. **onInputAvailable** - Complete input is parsed and validated
+4. Tool's **execute** function runs
+5. **onOutput** - Tool has completed successfully
+
+### Hook Parameters
+
+All hooks receive a parameter object with these common properties:
+
+- `toolCallId` (string): Unique identifier for this specific tool call
+- `abortSignal` (AbortSignal): Signal for detecting if the operation should be cancelled
+
+Additionally:
+- `onInputStart`, `onInputDelta`, and `onInputAvailable` receive `messages` (array): The conversation messages at the time of the tool call
+- `onInputDelta` receives `inputTextDelta` (string): The incremental text chunk
+- `onInputAvailable` receives `input`: The validated input data (typed according to `inputSchema`)
+- `onOutput` receives `output`: The tool's return value (typed according to `outputSchema`) and `toolName` (string): The name of the tool
+
+### Error Handling
+
+Hook errors are caught and logged automatically, but do not prevent tool execution from continuing. If a hook throws an error, it will be logged to the console but will not fail the tool call.
+
 ## Related
 
 - [MCP Overview](/docs/v1/mcp/overview)
 - [Using Tools with Agents](/docs/v1/agents/using-tools)
+- [Tool Streaming](/docs/v1/streaming/tool-streaming)
 - [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)

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

@@ -10,13 +10,13 @@ The `createGraphRAGTool()` creates a tool that enhances RAG by building a graph
 ## Usage Example
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { createGraphRAGTool } from "@mastra/rag";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 const graphTool = createGraphRAGTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   graphOptions: {
     dimension: 1536,
     threshold: 0.7,
@@ -193,7 +193,7 @@ The default description focuses on:
 const graphTool = createGraphRAGTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   graphOptions: {
     dimension: 1536,
     threshold: 0.8, // Higher similarity threshold
@@ -209,7 +209,7 @@ const graphTool = createGraphRAGTool({
 const graphTool = createGraphRAGTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: "openai/text-embedding-3-small	",
   description:
     "Analyze document relationships to find complex patterns and connections in our company's historical data",
 });
@@ -223,7 +223,7 @@ This example shows how to customize the tool description for a specific use case
 const graphTool = createGraphRAGTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: "openai/text-embedding-3-small	",
 });
 ```
 

package/.docs/raw/reference/tools/mcp-client.mdx

@@ -291,23 +291,6 @@ mcpClient.resources.onListChanged("myWeatherServer", () => {
 });
 ```
 
-### `prompts` Property
-
-The `MCPClient` instance has a `prompts` property that provides access to prompt-related operations.
-
-```typescript
-const mcpClient = new MCPClient({
-  /* ...servers configuration... */
-});
-
-// Access prompt methods via mcpClient.prompts
-const allPromptsByServer = await mcpClient.prompts.list();
-const { prompt, messages } = await mcpClient.prompts.get({
-  serverName: "myWeatherServer",
-  name: "current",
-});
-```
-
 ### `elicitation` Property
 
 The `MCPClient` instance has an `elicitation` property that provides access to elicitation-related operations. Elicitation allows MCP servers to request structured information from users.
@@ -451,6 +434,23 @@ await mcpClient.elicitation.onRequest("interactiveServer", async (request) => {
 });
 ```
 
+### `prompts` Property
+
+The `MCPClient` instance has a `prompts` property that provides access to prompt-related operations.
+
+```typescript
+const mcpClient = new MCPClient({
+  /* ...servers configuration... */
+});
+
+// Access prompt methods via mcpClient.prompts
+const allPromptsByServer = await mcpClient.prompts.list();
+const { prompt, messages } = await mcpClient.prompts.get({
+  serverName: "myWeatherServer",
+  name: "current",
+});
+```
+
 #### `prompts.list()`
 
 Retrieves all available prompts from all connected MCP servers, grouped by server name.
@@ -516,6 +516,63 @@ mcpClient.prompts.onListChanged("myWeatherServer", () => {
 });
 ```
 
+### `progress` Property
+
+The `MCPClient` instance has a `progress` property for subscribing to progress notifications emitted by MCP servers while tools execute.
+
+```typescript
+const mcpClient = new MCPClient({
+  servers: {
+    myServer: {
+      url: new URL('http://localhost:4111/api/mcp/myServer/mcp'),
+      // Enabled by default; set to false to disable
+      enableProgressTracking: true,
+    },
+  },
+});
+
+// Subscribe to progress updates for a specific server
+await mcpClient.progress.onUpdate('myServer', (params) => {
+  console.log('📊 Progress:', params.progress, '/', params.total);
+  if (params.message) console.log('Message:', params.message);
+  if (params.progressToken) console.log('Token:', params.progressToken);
+});
+```
+
+#### `progress.onUpdate(serverName: string, handler)`
+
+Registers a handler function to receive progress updates from the specified server.
+
+```typescript
+async onUpdate(
+  serverName: string,
+  handler: (params: {
+    progressToken: string;
+    progress: number;
+    total?: number;
+    message?: string;
+  }) => void,
+): Promise<void>
+```
+
+Notes:
+
+- When `enableProgressTracking` is true (default), tool calls include a `progressToken` so you can correlate updates to a specific run.
+- If you pass a `runId` when executing a tool, it will be used as the `progressToken`.
+
+To disable progress tracking for a server:
+
+```typescript
+const mcpClient = new MCPClient({
+  servers: {
+    myServer: {
+      url: new URL('http://localhost:4111/api/mcp/myServer/mcp'),
+      enableProgressTracking: false,
+    },
+  },
+});
+```
+
 ## Elicitation
 
 Elicitation is a feature that allows MCP servers to request structured information from users. When a server needs additional data, it can send an elicitation request that the client handles by prompting the user. A common example is during a tool call.
@@ -632,7 +689,6 @@ For tools where you have a single connection to the MCP server for you entire ap
 ```typescript
 import { MCPClient } from "@mastra/mcp";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 
 const mcp = new MCPClient({
   servers: {
@@ -657,7 +713,7 @@ const mcp = new MCPClient({
 const agent = new Agent({
   name: "Multi-tool Agent",
   instructions: "You have access to multiple tool servers.",
-  model: openai("gpt-4"),
+  model: "openai/gpt-5.1",
   tools: await mcp.listTools(),
 });
 
@@ -707,13 +763,12 @@ When you need a new MCP connection for each user, use `listToolsets()` and add t
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { MCPClient } from "@mastra/mcp";
-import { openai } from "@ai-sdk/openai";
 
 // Create the agent first, without any tools
 const agent = new Agent({
   name: "Multi-tool Agent",
   instructions: "You help users check stocks and weather.",
-  model: openai("gpt-4"),
+  model: "openai/gpt-5.1",
 });
 
 // Later, configure MCP with user-specific settings

package/.docs/raw/reference/tools/mcp-server.mdx

@@ -16,7 +16,6 @@ It supports both [stdio (subprocess) and SSE (HTTP) MCP transports](https://mode
 To create a new `MCPServer`, you need to provide some basic information about your server, the tools it will offer, and optionally, any agents you want to expose as tools.
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 import { createTool } from "@mastra/core/tools";
 import { MCPServer } from "@mastra/mcp";
@@ -28,7 +27,7 @@ const myAgent = new Agent({
   name: "MyExampleAgent",
   description: "A generalist to help with basic questions."
   instructions: "You are a helpful assistant.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
 });
 
 const weatherTool = createTool({