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

package/.docs/raw/reference/processors/moderation-processor.mdx

@@ -130,7 +130,7 @@ import { ModerationProcessor } from "@mastra/core/processors";
 export const agent = new Agent({
   name: "moderated-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   inputProcessors: [
     new ModerationProcessor({
       model: "openai/gpt-4.1-nano",
@@ -155,7 +155,7 @@ import { BatchPartsProcessor, ModerationProcessor } from "@mastra/core/processor
 export const agent = new Agent({
   name: "output-moderated-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   outputProcessors: [
     // Batch stream parts first to reduce LLM calls
     new BatchPartsProcessor({

package/.docs/raw/reference/processors/pii-detector.mdx

@@ -137,7 +137,7 @@ import { PIIDetector } from "@mastra/core/processors";
 export const agent = new Agent({
   name: "private-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   inputProcessors: [
     new PIIDetector({
       model: "openai/gpt-4.1-nano",
@@ -164,7 +164,7 @@ import { BatchPartsProcessor, PIIDetector } from "@mastra/core/processors";
 export const agent = new Agent({
   name: "output-pii-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   outputProcessors: [
     // Batch stream parts first to reduce LLM calls
     new BatchPartsProcessor({

package/.docs/raw/reference/processors/prompt-injection-detector.mdx

@@ -115,7 +115,7 @@ import { PromptInjectionDetector } from "@mastra/core/processors";
 export const agent = new Agent({
   name: "secure-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   inputProcessors: [
     new PromptInjectionDetector({
       model: "openai/gpt-4.1-nano",

package/.docs/raw/reference/processors/system-prompt-scrubber.mdx

@@ -10,11 +10,10 @@ The `SystemPromptScrubber` is an **output processor** that detects and handles s
 ## Usage example
 
 ```typescript copy
-import { openai } from "@ai-sdk/openai";
 import { SystemPromptScrubber } from "@mastra/core/processors";
 
 const processor = new SystemPromptScrubber({
-  model: openai("gpt-4.1-nano"),
+  model: "openai/gpt-4.1-nano",
   strategy: "redact",
   redactionMethod: "mask",
   includeDetections: true
@@ -131,7 +130,7 @@ import { BatchPartsProcessor, SystemPromptScrubber } from "@mastra/core/processo
 export const agent = new Agent({
   name: "scrubbed-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   outputProcessors: [
     // Batch stream parts first to reduce LLM calls
     new BatchPartsProcessor({

package/.docs/raw/reference/processors/token-limiter-processor.mdx

@@ -45,7 +45,7 @@ const processor = new TokenLimiterProcessor({
     {
       name: "encoding",
       type: "TiktokenBPE",
-      description: "Optional encoding to use. Defaults to o200k_base which is used by gpt-4o",
+      description: "Optional encoding to use. Defaults to o200k_base which is used by gpt-5.1",
       isOptional: true,
       default: "o200k_base",
     },
@@ -124,7 +124,7 @@ import { TokenLimiterProcessor } from "@mastra/core/processors";
 export const agent = new Agent({
   name: "limited-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   outputProcessors: [
     new TokenLimiterProcessor({
       limit: 1000,

package/.docs/raw/reference/processors/unicode-normalizer.mdx

@@ -101,7 +101,7 @@ import { UnicodeNormalizer } from "@mastra/core/processors";
 export const agent = new Agent({
   name: "normalized-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   inputProcessors: [
     new UnicodeNormalizer({
       stripControlChars: true,

package/.docs/raw/reference/rag/embeddings.mdx

@@ -13,9 +13,10 @@ The `embed` function generates a vector embedding for a single text input:
 
 ```typescript
 import { embed } from "ai";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 const result = await embed({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   value: "Your text to embed",
   maxRetries: 2, // optional, defaults to 2
 });
@@ -80,7 +81,7 @@ For embedding multiple texts at once, use the `embedMany` function:
 import { embedMany } from "ai";
 
 const result = await embedMany({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   values: ["First text", "Second text", "Third text"],
   maxRetries: 2, // optional, defaults to 2
 });
@@ -142,17 +143,16 @@ const result = await embedMany({
 
 ```typescript
 import { embed, embedMany } from "ai";
-import { openai } from "@ai-sdk/openai";
 
 // Single embedding
 const singleResult = await embed({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   value: "What is the meaning of life?",
 });
 
 // Multiple embeddings
 const multipleResult = await embedMany({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   values: [
     "First question about life",
     "Second question about universe",

package/.docs/raw/reference/rag/rerank.mdx

@@ -19,10 +19,9 @@ function rerank(
 ## Usage Example
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { rerank } from "@mastra/rag";
 
-const model = openai("gpt-4o-mini");
+const model = "openai/gpt-5.1";
 
 const rerankedResults = await rerank(
   vectorSearchResults,

package/.docs/raw/reference/rag/rerankWithScorer.mdx

@@ -19,7 +19,6 @@ function rerankWithScorer({
 ## Usage Example
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { rerankWithScorer as rerank, CohereRelevanceScorer } from "@mastra/rag";
 
 const scorer = new CohereRelevanceScorer("rerank-v3.5");

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

@@ -3,6 +3,8 @@ 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.
@@ -252,6 +254,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 +405,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",
@@ -661,13 +586,6 @@ const aiSdkStream = await agent.stream("message for agent", {
         },
       ],
     },
-    {
-      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,7 +708,7 @@ 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

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

@@ -632,7 +632,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 +656,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 +706,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({