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

package/.docs/raw/agents/adding-voice.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Adding Voice to Agents | Agents | Mastra Docs"
+title: "Adding Voice to Agents | Agents"
 ---
 
 # Adding Voice to Agents
@@ -15,7 +15,6 @@ import { createReadStream } from "fs";
 import path from "path";
 import { Agent } from "@mastra/core/agent";
 import { OpenAIVoice } from "@mastra/voice-openai";
-import { openai } from "@ai-sdk/openai";
 
 // Initialize the voice provider with default settings
 const voice = new OpenAIVoice();
@@ -25,7 +24,7 @@ export const agent = new Agent({
   id: "voice-agent",
   name: "Voice Agent",
   instructions: `You are a helpful assistant with both STT and TTS capabilities.`,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   voice,
 });
 
@@ -105,7 +104,7 @@ import { search, calculate } from "../tools";
 // Initialize the realtime voice provider
 const voice = new OpenAIRealtimeVoice({
   apiKey: process.env.OPENAI_API_KEY,
-  model: "gpt-4o-mini-realtime",
+  model: "gpt-5.1-realtime",
   speaker: "alloy",
 });
 
@@ -114,7 +113,7 @@ export const agent = new Agent({
   id: "speech-to-speech-agent",
   name: "Speech-to-Speech Agent",
   instructions: `You are a helpful assistant with speech-to-speech capabilities.`,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   tools: {
     // Tools configured on Agent are passed to voice provider
     search,
@@ -178,7 +177,6 @@ import { Agent } from "@mastra/core/agent";
 import { CompositeVoice } from "@mastra/core/voice";
 import { OpenAIVoice } from "@mastra/voice-openai";
 import { Mastra } from "@mastra/core";
-import { openai } from "@ai-sdk/openai";
 
 // Saves an audio stream to a file in the audio directory, creating the directory if it doesn't exist.
 export const saveAudioToFile = async (
@@ -217,7 +215,7 @@ export const convertToText = async (
 export const hybridVoiceAgent = new Agent({
   id: "hybrid-voice-agent",
   name: "Hybrid Voice Agent",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions: "You can speak and listen using different providers.",
   voice: new CompositeVoice({
     input: new OpenAIVoice(),
@@ -229,7 +227,7 @@ export const unifiedVoiceAgent = new Agent({
   id: "unified-voice-agent",
   name: "Unified Voice Agent",
   instructions: "You are an agent with both STT and TTS capabilities.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   voice: new OpenAIVoice(),
 });
 
@@ -269,13 +267,12 @@ import { Agent } from "@mastra/core/agent";
 import { CompositeVoice } from "@mastra/core/voice";
 import { OpenAIVoice } from "@mastra/voice-openai";
 import { PlayAIVoice } from "@mastra/voice-playai";
-import { openai } from "@ai-sdk/openai";
 
 export const agent = new Agent({
   id: "voice-agent",
   name: "Voice Agent",
   instructions: `You are a helpful assistant with both STT and TTS capabilities.`,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
 
   // Create a composite voice using OpenAI for listening and PlayAI for speaking
   voice: new CompositeVoice({
@@ -285,6 +282,55 @@ export const agent = new Agent({
 });
 ```
 
+### Using AI SDK
+
+Mastra supports using AI SDK's transcription and speech models directly in `CompositeVoice`, giving you access to a wide range of providers through the AI SDK ecosystem:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { CompositeVoice } from "@mastra/core/voice";
+import { openai } from "@ai-sdk/openai";
+import { elevenlabs } from "@ai-sdk/elevenlabs";
+import { groq } from "@ai-sdk/groq";
+
+export const agent = new Agent({
+  id: "aisdk-voice-agent",
+  name: "AI SDK Voice Agent",
+  instructions: `You are a helpful assistant with voice capabilities.`,
+  model: openai("gpt-5.1"),
+
+  // Pass AI SDK models directly to CompositeVoice
+  voice: new CompositeVoice({
+    input: openai.transcription('whisper-1'),      // AI SDK transcription model
+    output: elevenlabs.speech('eleven_turbo_v2'),  // AI SDK speech model
+  }),
+});
+
+// Use voice capabilities as usual
+const audioStream = await agent.voice.speak("Hello!");
+const transcribedText = await agent.voice.listen(audioStream);
+```
+
+#### Mix and Match Providers
+
+You can mix AI SDK models with Mastra voice providers:
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { PlayAIVoice } from "@mastra/voice-playai";
+import { openai } from "@ai-sdk/openai";
+
+// Use AI SDK for transcription and Mastra provider for speech
+const voice = new CompositeVoice({
+  input: openai.transcription('whisper-1'),  // AI SDK
+  output: new PlayAIVoice(),                  // Mastra provider
+});
+```
+
+For the complete list of supported AI SDK providers and their capabilities:
+* [Transcription](https://ai-sdk.dev/docs/providers/openai/transcription)
+* [Speech](https://ai-sdk.dev/docs/providers/elevenlabs/speech)
+
 ## Supported Voice Providers
 
 Mastra supports multiple voice providers for text-to-speech (TTS) and speech-to-text (STT) capabilities:

package/.docs/raw/agents/agent-approval.mdx

@@ -0,0 +1,189 @@
+---
+title: "Agent Approval | Agents"
+description: Learn how to require approvals and suspend tool execution while keeping humans in control of agent workflows.
+---
+
+# Agent Approval
+
+Agents sometimes require the same [human-in-the-loop](/docs/v1/workflows/human-in-the-loop) oversight used in workflows when calling tools that handle sensitive operations, like deleting resources or performing running long processes. With agent approval you can suspend a tool call and provide feedback to the user, or approve or decline a tool call based on targeted application conditions.
+
+## Tool call approval
+
+Tool call approval can be enabled at the agent level and apply to every tool the agent uses, or at the tool level providing more granular control over individual tool calls.
+
+### Storage
+
+Agent approval uses a snapshot to capture the state of the request. Ensure you've enabled a storage provider in your main Mastra instance. If storage isn't enabled you'll see an error relating to snapshot not found.
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core/mastra";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const mastra = new Mastra({
+  // ...
+  storage: new LibSQLStore({
+    id: "mastra-storage",
+    url: ":memory:"
+  })
+});
+```
+
+
+## Agent-level approval
+
+When calling an agent using `.stream()` set `requireToolApproval` to `true` which will prevent the agent from calling any of the tools defined in its configuration.
+
+```typescript showLineNumbers
+const stream = await agent.stream("What's the weather in London?", {
+  requireToolApproval: true
+});
+```
+
+### Approving tool calls
+
+To approve a tool call, access `approveToolCall` from the `agent`, passing in the `runId` of the stream. This will let the agent know its now OK to call its tools.
+
+```typescript showLineNumbers
+const handleApproval = async () => {
+  const approvedStream = await agent.approveToolCall({ runId: stream.runId });
+
+  for await (const chunk of approvedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+```
+
+### Declining tool calls
+
+To decline a tool call, access the `declineToolCall` from the `agent`. You will see the streamed response from the agent, but it won't call its tools.
+
+```typescript showLineNumbers
+const handleDecline = async () => {
+  const declinedStream = await agent.declineToolCall({ runId: stream.runId });
+
+  for await (const chunk of declinedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+```
+
+## Tool-level approval
+
+There are two types of tool call approval. The first uses `requireApproval`, which is a property on the tool definition, while `requireToolApproval` is a parameter passed to `agent.stream()`. The second uses `suspend` and lets the agent provide context or confirmation prompts so the user can decide whether the tool call should continue.
+
+### Tool approval using `requireToolApproval`
+
+In this approach, `requireApproval` is configured on the tool definition (shown below) rather than on the agent.
+
+```typescript
+export const testTool = createTool({
+  id: "test-tool",
+  description: "Fetches weather for a location",
+  inputSchema: z.object({
+    location: z.string()
+  }),
+  outputSchema: z.object({
+    weather: z.string()
+  }),
+  resumeSchema: z.object({
+    approved: z.boolean()
+  }),
+  execute: async ({ location }) => {
+    const response = await fetch(`https://wttr.in/${location}?format=3`);
+    const weather = await response.text();
+
+    return { weather };
+  },
+  requireApproval: true
+});
+```
+
+When `requireApproval` is true for a tool, the stream will include chunks of type `tool-call-approval` to indicate that the call is paused. To continue the call, invoke `resumeStream` with the required `resumeSchema` and the `runId`.
+
+```typescript
+const stream = await agent.stream("What's the weather in London?");
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === "tool-call-approval") {
+    console.log("Approval required.");
+  }
+}
+
+const handleResume = async () => {
+  const resumedStream = await agent.resumeStream({ approved: true }, { runId: stream.runId });
+
+  for await (const chunk of resumedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+```
+
+
+### Tool approval using `suspend`
+
+With this approach, neither the agent nor the tool uses `requireApproval`. Instead, the tool implementation calls `suspend` to pause execution and return context or confirmation prompts to the user.
+
+```typescript
+
+export const testToolB = createTool({
+  id: "test-tool-b",
+  description: "Fetches weather for a location",
+  inputSchema: z.object({
+    location: z.string()
+  }),
+  outputSchema: z.object({
+    weather: z.string()
+  }),
+  resumeSchema: z.object({
+    approved: z.boolean()
+  }),
+  suspendSchema: z.object({
+    reason: z.string()
+  }),
+  execute: async ({ location }, { agent } = {}) => {
+    const { resumeData: { approved } = {}, suspend } = agent ?? {};
+
+    if (!approved) {
+      return suspend?.({ reason: "Approval required." });
+    }
+
+    const response = await fetch(`https://wttr.in/${location}?format=3`);
+    const weather = await response.text();
+
+    return { weather };
+  }
+});
+```
+
+With this approach the stream will include a `tool-call-suspended` chunk, and the `suspendPayload` will contain the `reason` defined by the tool's `suspendSchema`. To continue the call, invoke `resumeStream` with the required `resumeSchema` and the `runId`.
+
+```typescript
+const stream = await agent.stream("What's the weather in London?");
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === "tool-call-suspended") {
+    console.log(chunk.payload.suspendPayload);
+  }
+}
+
+const handleResume = async () => {
+  const resumedStream = await agent.resumeStream({ approved: true }, { runId: stream.runId });
+
+  for await (const chunk of resumedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+
+```
+
+## Related
+
+- [Using Tools](./using-tools)
+- [Agent Overview](./overview)
+- [Tools Overview](../mcp/overview)
+- [Agent Memory](./agent-memory)
+- [Request Context](/docs/v1/server-db/request-context)

package/.docs/raw/agents/agent-memory.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Agent Memory | Agents | Mastra Docs"
+title: "Agent Memory | Agents"
 description: Learn how to add memory to agents to store conversation history and maintain context across interactions.
 ---
 
@@ -21,7 +21,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
 To enable memory in Mastra, install the `@mastra/memory` package along with a storage provider.
 
 ```bash npm2yarn copy
-npm install @mastra/memory@latest @mastra/libsql@latest
+npm install @mastra/memory@beta @mastra/libsql@beta
 ```
 
 ## Storage providers

package/.docs/raw/agents/guardrails.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Guardrails | Agents | Mastra Docs"
+title: "Guardrails | Agents"
 description: "Learn how to implement guardrails using input and output processors to secure and control AI interactions."
 ---
 
@@ -22,8 +22,7 @@ Use processors for content moderation, prompt injection prevention, response san
 
 Import and instantiate the relevant processor class, and pass it to your agent’s configuration using either the `inputProcessors` or `outputProcessors` option:
 
-```typescript {3,9-17} title="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
+```typescript {2,8-16} title="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
 import { Agent } from "@mastra/core/agent";
 import { ModerationProcessor } from "@mastra/core/processors";
 
@@ -31,10 +30,10 @@ export const moderatedAgent = new Agent({
   id: "moderated-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"),
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       categories: ["hate", "harassment", "violence"],
       threshold: 0.7,
       strategy: "block",
@@ -52,7 +51,7 @@ Input processors are applied before user messages reach the language model. They
 
 The `UnicodeNormalizer` is an input processor that cleans and normalizes user input by unifying Unicode characters, standardizing whitespace, and removing problematic symbols, allowing the LLM to better understand user messages.
 
-```typescript {6-9} title="src/mastra/agents/normalized-agent.ts" showLineNumbers copy
+```typescript {8-11} title="src/mastra/agents/normalized-agent.ts" showLineNumbers copy
 import { UnicodeNormalizer } from "@mastra/core/processors";
 
 export const normalizedAgent = new Agent({
@@ -74,7 +73,7 @@ export const normalizedAgent = new Agent({
 
 The `PromptInjectionDetector` is an input processor that scans user messages for prompt injection, jailbreak attempts, and system override patterns. It uses an LLM to classify risky input and can block or rewrite it before it reaches the model.
 
-```typescript {6-11} title="src/mastra/agents/secure-agent.ts" showLineNumbers copy
+```typescript {8-13} title="src/mastra/agents/secure-agent.ts" showLineNumbers copy
 import { PromptInjectionDetector } from "@mastra/core/processors";
 
 export const secureAgent = new Agent({
@@ -83,7 +82,7 @@ export const secureAgent = new Agent({
   // ...
   inputProcessors: [
     new PromptInjectionDetector({
-      model: openai("gpt-4.1-nano"),
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       threshold: 0.8,
       strategy: "rewrite",
       detectionTypes: ["injection", "jailbreak", "system-override"],
@@ -98,7 +97,7 @@ export const secureAgent = new Agent({
 
 The `LanguageDetector` is an input processor that detects and translates user messages into a target language, enabling multilingual support while maintaining consistent interaction. It uses an LLM to identify the language and perform the translation.
 
-```typescript {6-11} title="src/mastra/agents/multilingual-agent.ts" showLineNumbers copy
+```typescript {8-13} title="src/mastra/agents/multilingual-agent.ts" showLineNumbers copy
 import { LanguageDetector } from "@mastra/core/processors";
 
 export const multilingualAgent = new Agent({
@@ -107,7 +106,7 @@ export const multilingualAgent = new Agent({
   // ...
   inputProcessors: [
     new LanguageDetector({
-      model: openai("gpt-4.1-nano"),
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       targetLanguages: ["English", "en"],
       strategy: "translate",
       threshold: 0.8,
@@ -126,7 +125,7 @@ Output processors are applied after the language model generates a response, but
 
 The `BatchPartsProcessor` is an output processor that combines multiple stream parts before emitting them to the client. This reduces network overhead and improves the user experience by consolidating small chunks into larger batches.
 
-```typescript {6-10} title="src/mastra/agents/batched-agent.ts" showLineNumbers copy
+```typescript {8-12} title="src/mastra/agents/batched-agent.ts" showLineNumbers copy
 import { BatchPartsProcessor } from "@mastra/core/processors";
 
 export const batchedAgent = new Agent({
@@ -149,7 +148,7 @@ export const batchedAgent = new Agent({
 
 The `TokenLimiterProcessor` is an output processor that limits the number of tokens in model responses. It helps manage cost and performance by truncating or blocking messages when the limit is exceeded.
 
-```typescript {6-10, 13-15} title="src/mastra/agents/limited-agent.ts" showLineNumbers copy
+```typescript {8-12} title="src/mastra/agents/limited-agent.ts" showLineNumbers copy
 import { TokenLimiterProcessor } from "@mastra/core/processors";
 
 export const limitedAgent = new Agent({
@@ -172,7 +171,7 @@ export const limitedAgent = new Agent({
 
 The `SystemPromptScrubber` is an output processor that detects and redacts system prompts or other internal instructions from model responses. It helps prevent unintended disclosure of prompt content or configuration details that could introduce security risks. It uses an LLM to identify and redact sensitive content based on configured detection types.
 
-```typescript {5-13} title="src/mastra/agents/scrubbed-agent.ts" copy showLineNumbers
+```typescript {7-16} title="src/mastra/agents/scrubbed-agent.ts" copy showLineNumbers
 import { SystemPromptScrubber } from "@mastra/core/processors";
 
 const scrubbedAgent = new Agent({
@@ -180,7 +179,7 @@ const scrubbedAgent = new Agent({
   name: "Scrubbed Agent",
   outputProcessors: [
     new SystemPromptScrubber({
-      model: openai("gpt-4.1-nano"),
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       strategy: "redact",
       customPatterns: ["system prompt", "internal instructions"],
       includeDetections: true,
@@ -195,6 +194,10 @@ const scrubbedAgent = new Agent({
 
 > See [SystemPromptScrubber](/reference/v1/processors/system-prompt-scrubber) for a full list of configuration options.
 
+:::note
+When streaming responses over HTTP, Mastra redacts sensitive request data (system prompts, tool definitions, API keys) from stream chunks at the server level by default. See [Stream data redaction](/docs/v1/server-db/mastra-server#stream-data-redaction) for details.
+:::
+
 ## Hybrid processors
 
 Hybrid processors can be applied either before messages are sent to the language model or before responses are returned to the user. They are useful for tasks like content moderation and PII redaction.
@@ -203,7 +206,7 @@ Hybrid processors can be applied either before messages are sent to the language
 
 The `ModerationProcessor` is a hybrid processor that detects inappropriate or harmful content across categories like hate, harassment, and violence. It can be used to moderate either user input or model output, depending on where it's applied. It uses an LLM to classify the message and can block or rewrite it based on your configuration.
 
-```typescript {6-11, 14-16} title="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
+```typescript {8-13,16-18} title="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
 import { ModerationProcessor } from "@mastra/core/processors";
 
 export const moderatedAgent = new Agent({
@@ -212,7 +215,7 @@ export const moderatedAgent = new Agent({
   // ...
   inputProcessors: [
     new ModerationProcessor({
-      model: openai("gpt-4.1-nano"),
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       threshold: 0.7,
       strategy: "block",
       categories: ["hate", "harassment", "violence"],
@@ -232,7 +235,7 @@ export const moderatedAgent = new Agent({
 
 The `PIIDetector` is a hybrid processor that detects and removes personally identifiable information such as emails, phone numbers, and credit cards. It can redact either user input or model output, depending on where it's applied. It uses an LLM to identify sensitive content based on configured detection types.
 
-```typescript {6-13, 16-18} title="src/mastra/agents/private-agent.ts" showLineNumbers copy
+```typescript {8-15,18-20} title="src/mastra/agents/private-agent.ts" showLineNumbers copy
 import { PIIDetector } from "@mastra/core/processors";
 
 export const privateAgent = new Agent({
@@ -241,7 +244,7 @@ export const privateAgent = new Agent({
   // ...
   inputProcessors: [
     new PIIDetector({
-      model: openai("gpt-4.1-nano"),
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       threshold: 0.6,
       strategy: "redact",
       redactionMethod: "mask",
@@ -306,7 +309,7 @@ Many of the built-in processors support a `strategy` parameter that controls how
 
 Most strategies allow the request to continue without interruption. When `block` is used, the processor calls its internal `abort()` function, which immediately stops the request and prevents any subsequent processors from running.
 
-```typescript {8} title="src/mastra/agents/private-agent.ts" showLineNumbers copy
+```typescript {10} title="src/mastra/agents/private-agent.ts" showLineNumbers copy
 import { PIIDetector } from "@mastra/core/processors";
 
 export const privateAgent = new Agent({
@@ -330,7 +333,7 @@ For example, if an agent uses the `PIIDetector` with `strategy: "block"` and the
 
 #### `.generate()` example
 
-```typescript {3-4, } showLineNumbers
+```typescript showLineNumbers
 const result = await agent.generate(
   "Is this credit card number valid?: 4543 1374 5089 4332",
 );
@@ -341,7 +344,7 @@ console.error(result.tripwireReason);
 
 #### `.stream()` example
 
-```typescript {4-5} showLineNumbers
+```typescript showLineNumbers
 const stream = await agent.stream(
   "Is this credit card number valid?: 4543 1374 5089 4332",
 );
@@ -365,6 +368,6 @@ If the built-in processors don’t cover your needs, you can create your own by
 
 Available examples:
 
-- [Message Length Limiter](/examples/v1/processors/message-length-limiter)
-- [Response Length Limiter](/examples/v1/processors/response-length-limiter)
-- [Response Validator](/examples/v1/processors/response-validator)
+- [Message Length Limiter](https://github.com/mastra-ai/mastra/tree/main/examples/processors-message-length-limiter)
+- [Response Length Limiter](https://github.com/mastra-ai/mastra/tree/main/examples/processors-response-length-limiter)
+- [Response Validator](https://github.com/mastra-ai/mastra/tree/main/examples/processors-response-validator)

package/.docs/raw/agents/networks.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Agent Networks | Agents | Mastra Docs"
+title: "Agent Networks | Agents"
 description: Learn how to coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
 ---
 
@@ -24,7 +24,6 @@ Mastra agent networks operate using these principles:
 An agent network is built around a top-level routing agent that delegates tasks to agents, workflows, and tools defined in its configuration. Memory is configured on the routing agent using the `memory` option, and `instructions` define the agent's routing behavior.
 
 ```typescript {22-23,26,29} title="src/mastra/agents/routing-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
@@ -44,7 +43,7 @@ export const routingAgent = new Agent({
       Always respond with a complete report—no bullet points.
       Write in full paragraphs, like a blog post.
       Do not answer with incomplete or uncertain information.`,
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   agents: {
     researchAgent,
     writingAgent,
@@ -241,3 +240,4 @@ network-execution-event-step-finish
 - [Agent Memory](./agent-memory)
 - [Workflows Overview](../workflows/overview)
 - [Request Context](/docs/v1/server-db/request-context)
+- [Supervisor example](https://github.com/mastra-ai/mastra/tree/main/examples/supervisor-agent)