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

package/.docs/raw/streaming/overview.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Streaming Overview | Streaming"
 description: "Streaming in Mastra enables real-time, incremental responses from both agents and workflows, providing immediate feedback as AI-generated content is produced."
+packages:
+  - "@mastra/ai-sdk"
 ---
 
 # Streaming Overview
@@ -11,7 +13,7 @@ Mastra supports real-time, incremental responses from agents and workflows, allo
 
 Mastra's streaming API adapts based on your model version:
 
-- **`.stream()`**: For V2 models, supports **AI SDK v5** (`LanguageModelV2`).
+- **`.stream()`**: For V2 models, supports **AI SDK v5** and later (`LanguageModelV2`).
 - **`.streamLegacy()`**: For V1 models, supports **AI SDK v4** (`LanguageModelV1`).
 
 ## Streaming with agents
@@ -22,7 +24,7 @@ You can pass a single string for simple prompts, an array of strings when provid
 
 A `textStream` breaks the response into chunks as it's generated, allowing output to stream progressively instead of arriving all at once. Iterate over the `textStream` using a `for await` loop to inspect each stream chunk.
 
-```typescript {3,7} showLineNumbers copy
+```typescript {3,7}
 const testAgent = mastra.getAgent("testAgent");
 
 const stream = await testAgent.stream([
@@ -34,7 +36,11 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
-> See [Agent.stream()](/reference/v1/streaming/agents/stream) for more information.
+:::info
+
+Visit [Agent.stream()](/reference/v1/streaming/agents/stream) for more information.
+
+:::
 
 ### Output from `Agent.stream()`
 
@@ -56,13 +62,13 @@ An agent stream provides access to various response properties:
 - **`stream.finishReason`**: The reason the agent stopped streaming.
 - **`stream.usage`**: Token usage information.
 
-### AI SDK v5 Compatibility
+### AI SDK v5+ Compatibility
 
-AI SDK v5 uses `LanguageModelV2` for the model providers. If you are getting an error that you are using an AI SDK v4 model you will need to upgrade your model package to the next major version.
+AI SDK v5 (and later) uses `LanguageModelV2` for the model providers. If you are getting an error that you are using an AI SDK v4 model you will need to upgrade your model package to the next major version.
 
-For integration with AI SDK v5, use the `toAISdkV5Stream()` utility from `@mastra/ai-sdk` to convert Mastra streams to AI SDK-compatible format:
+For integration with AI SDK v5+, use the `toAISdkV5Stream()` utility from `@mastra/ai-sdk` to convert Mastra streams to AI SDK-compatible format:
 
-```typescript {2,9-12} showLineNumbers copy
+```typescript {2,9-12}
 import { toAISdkV5Stream } from "@mastra/ai-sdk";
 
 const testAgent = mastra.getAgent("testAgent");
@@ -71,15 +77,15 @@ const stream = await testAgent.stream([
   { role: "user", content: "Help me organize my day" },
 ]);
 
-// Convert to AI SDK v5 compatible stream
+// Convert to AI SDK v5+ compatible stream
 const aiSDKStream = toAISdkV5Stream(stream, { from: "agent" });
 
-// Use with AI SDK v5 methods
+// Use with AI SDK v5+ methods
 ```
 
-For converting messages to AI SDK v5 format, use the `toAISdkV5Messages()` utility from `@mastra/ai-sdk/ui`:
+For converting messages to AI SDK v5+ format, use the `toAISdkV5Messages()` utility from `@mastra/ai-sdk/ui`:
 
-```typescript {1,4} showLineNumbers copy
+```typescript {1,4}
 import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
 
 const messages = [{ role: "user", content: "Hello" }];
@@ -92,7 +98,7 @@ The `network()` method enables multi-agent collaboration by executing a network
 
 > **Note**: This method is experimental and requires memory to be configured on the agent.
 
-```typescript {3,5-7} showLineNumbers copy
+```typescript {3,5-7}
 const testAgent = mastra.getAgent("testAgent");
 
 const networkStream = await testAgent.network("Help me organize my day");
@@ -102,7 +108,11 @@ for await (const chunk of networkStream) {
 }
 ```
 
-> See [Agent.network()](/reference/v1/agents/network) for more information.
+:::info
+
+Visit [Agent.network()](/reference/v1/agents/network) for more information.
+
+:::
 
 #### Network stream properties
 
@@ -112,7 +122,7 @@ The network stream provides access to execution information:
 - **`networkStream.result`**: Promise resolving to the complete execution results
 - **`networkStream.usage`**: Promise resolving to token usage information
 
-```typescript {9-11} showLineNumbers copy
+```typescript {9-11}
 const testAgent = mastra.getAgent("testAgent");
 
 const networkStream = await testAgent.network(
@@ -136,7 +146,7 @@ Streaming from a workflow returns a sequence of structured events describing the
 
 The `stream()` method returns a `ReadableStream` of events directly.
 
-```typescript {3,9} showLineNumbers copy
+```typescript {3,9}
 const run = await testWorkflow.createRun();
 
 const stream = await run.stream({
@@ -150,14 +160,17 @@ for await (const chunk of stream) {
 }
 ```
 
-> See [Run.stream()](/reference/v1/streaming/workflows/stream) method documentation for more information.
+:::info
+
+Visit [Run.stream()](/reference/v1/streaming/workflows/stream) for more information.
+
+:::
 
 ### Output from `Run.stream()`
 
 The event structure includes `runId` and `from` at the top level, making it easier to identify and track workflow runs without digging into the payload.
 
 ```typescript
-// ...
 {
   type: 'workflow-start',
   runId: '1eeaf01a-d2bf-4e3f-8d1b-027795ccd3df',

package/.docs/raw/streaming/tool-streaming.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Tool streaming | Streaming"
 description: "Learn how to use tool streaming in Mastra, including handling tool calls, tool results, and tool execution events during streaming."
+packages:
+  - "@mastra/core"
 ---
 
 # Tool streaming
@@ -18,7 +20,7 @@ By combining writable tool streams with agent streaming, you gain fine grained c
 
 Agent streaming can be combined with tool calls, allowing tool outputs to be written directly into the agent’s streaming response. This makes it possible to surface tool activity as part of the overall interaction.
 
-```typescript {2,9} showLineNumbers copy
+```typescript {2,9}
 import { Agent } from "@mastra/core/agent";
 import { testTool } from "../tools/test-tool";
 
@@ -41,7 +43,7 @@ You must `await` the call to `writer.write()` or else you will lock the stream a
 
 :::
 
-```typescript {4,7,14} showLineNumbers copy
+```typescript {4,7,14}
 import { createTool } from "@mastra/core/tools";
 
 export const testTool = createTool({
@@ -70,7 +72,7 @@ export const testTool = createTool({
 You can also use `writer.custom()` if you want to emit top level stream chunks, This useful and relevant when
 integrating with UI Frameworks
 
-```typescript {4,7,14} showLineNumbers copy
+```typescript {4,7,14}
 import { createTool } from "@mastra/core/tools";
 
 export const testTool = createTool({
@@ -100,7 +102,7 @@ export const testTool = createTool({
 
 Events written to the stream are included in the emitted chunks. These chunks can be inspected to access any custom fields, such as event types, intermediate values, or tool-specific data.
 
-```typescript showLineNumbers copy
+```typescript
 const stream = await testAgent.stream([
   "What is the weather in London?",
   "Use the testTool",
@@ -119,7 +121,7 @@ Tools support lifecycle hooks that allow you to monitor different stages of tool
 
 ### Example: Using onInputAvailable and onOutput
 
-```typescript showLineNumbers copy
+```typescript
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 
@@ -161,7 +163,7 @@ For detailed documentation on all lifecycle hooks, see the [createTool() referen
 
 Pipe an agent's `fullStream` to the tool's `writer`. This streams partial output, and Mastra automatically aggregates the agent's usage into the tool run.
 
-```typescript showLineNumbers copy
+```typescript
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 

package/.docs/raw/streaming/workflow-streaming.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Workflow streaming | Streaming"
 description: "Learn how to use workflow streaming in Mastra, including handling workflow execution events, step streaming, and workflow integration with agents and tools."
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow streaming
@@ -24,13 +26,12 @@ You must `await` the call to `writer.write(...)` or else you will lock the strea
 
 :::
 
-```typescript {5,8,15} showLineNumbers copy
+```typescript {5,7,14}
 import { createStep } from "@mastra/core/workflows";
 
 export const testStep = createStep({
-  // ...
   execute: async ({ inputData, writer }) => {
-     const { value } = inputData;
+    const { value } = inputData;
 
     await writer?.write({
       type: "custom-event",
@@ -39,7 +40,7 @@ export const testStep = createStep({
 
     const response = await fetch(...);
 
-   await writer?.write({
+    await writer?.write({
       type: "custom-event",
       status: "success"
     });
@@ -55,7 +56,7 @@ export const testStep = createStep({
 
 Events written to the stream are included in the emitted chunks. These chunks can be inspected to access any custom fields, such as event types, intermediate values, or step-specific data.
 
-```typescript showLineNumbers copy
+```typescript
 const testWorkflow = mastra.getWorkflow("testWorkflow");
 
 const run = await testWorkflow.createRun();
@@ -86,7 +87,7 @@ if (result!.status === "suspended") {
 
 If a workflow stream is closed or interrupted for any reason, you can resume it with the `resumeStream` method. This will return a new `ReadableStream` that you can use to observe the workflow events.
 
-```typescript showLineNumbers copy
+```typescript
 const newStream = await run.resumeStream();
 
 for await (const chunk of newStream) {
@@ -98,12 +99,11 @@ for await (const chunk of newStream) {
 
 Pipe an agent's `textStream` to the workflow step's `writer`. This streams partial output, and Mastra automatically aggregates the agent's usage into the workflow run.
 
-```typescript showLineNumbers copy
+```typescript
 import { createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
 export const testStep = createStep({
-  // ...
   execute: async ({ inputData, mastra, writer }) => {
     const { city } = inputData;
 

package/.docs/raw/tools-mcp/advanced-usage.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Advanced Tool Usage | Tools & MCP"
 description: This page covers advanced features for Mastra tools, including abort signals and compatibility with the Vercel AI SDK tool format.
+packages:
+  - "@mastra/core"
 ---
 
 # Advanced Tool Usage
@@ -82,13 +84,13 @@ Mastra maintains compatibility with the tool format used by the Vercel AI SDK (`
 
 First, ensure you have the `ai` package installed:
 
-```bash npm2yarn copy
+```bash npm2yarn
 npm install ai
 ```
 
 Here's an example of a tool defined using the Vercel AI SDK format:
 
-```typescript title="src/mastra/tools/vercelWeatherTool.ts" copy
+```typescript title="src/mastra/tools/vercelWeatherTool.ts"
 import { tool } from "ai";
 import { z } from "zod";
 

package/.docs/raw/tools-mcp/mcp-overview.mdx

@@ -1,6 +1,9 @@
 ---
 title: "MCP Overview | Tools & MCP"
 description: Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
+packages:
+  - "@mastra/core"
+  - "@mastra/mcp"
 ---
 
 import Tabs from "@theme/Tabs";
@@ -29,7 +32,7 @@ npm install @mastra/mcp@beta
 
 The `MCPClient` connects Mastra primitives to external MCP servers, which can be local packages (invoked using `npx`) or remote HTTP(S) endpoints. Each server must be configured with either a `command` or a `url`, depending on how it's hosted.
 
-```typescript title="src/mastra/mcp/test-mcp-client.ts" showLineNumbers copy
+```typescript title="src/mastra/mcp/test-mcp-client.ts"
 import { MCPClient } from "@mastra/mcp";
 
 export const testMcpClient = new MCPClient({
@@ -48,13 +51,23 @@ export const testMcpClient = new MCPClient({
 });
 ```
 
-> See [MCPClient](/reference/v1/tools/mcp-client) for a full list of configuration options.
+:::info
+
+Visit [MCPClient](/reference/v1/tools/mcp-client) for a full list of configuration options.
+
+:::
+
+:::tip Authentication
+
+For connecting to OAuth-protected MCP servers, see the [OAuth Authentication](/reference/v1/tools/mcp-client#oauth-authentication) section.
+
+:::
 
 ## Using `MCPClient` with an agent
 
 To use tools from an MCP server in an agent, import your `MCPClient` and call `.listTools()` in the `tools` parameter. This loads from the defined MCP servers, making them available to the agent.
 
-```typescript {3,15} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
+```typescript {3,15} title="src/mastra/agents/test-agent.ts"
 import { Agent } from "@mastra/core/agent";
 
 import { testMcpClient } from "../mcp/test-mcp-client";
@@ -74,13 +87,17 @@ export const testAgent = new Agent({
 });
 ```
 
-> See the [Agent Class](/reference/v1/agents/agent) for a full list of configuration options.
+:::info
+
+Visit [Agent Class](/reference/v1/agents/agent) for a full list of configuration options.
+
+:::
 
 ## Configuring `MCPServer`
 
 To expose agents, tools, and workflows from your Mastra application to external systems over HTTP(S) use the `MCPServer` class. This makes them accessible to any system or agent that supports the protocol.
 
-```typescript title="src/mastra/mcp/test-mcp-server.ts" showLineNumbers copy
+```typescript title="src/mastra/mcp/test-mcp-server.ts"
 import { MCPServer } from "@mastra/mcp";
 
 import { testAgent } from "../agents/test-agent";
@@ -97,7 +114,17 @@ export const testMcpServer = new MCPServer({
 });
 ```
 
-> See [MCPServer](/reference/v1/tools/mcp-server) for a full list of configuration options.
+:::info
+
+Visit [MCPServer](/reference/v1/tools/mcp-server) for a full list of configuration options.
+
+:::
+
+:::tip Authentication
+
+To protect your MCP server with OAuth, see the [OAuth Protection](/reference/v1/tools/mcp-server#oauth-protection) section.
+
+:::
 
 ### Serverless deployments
 
@@ -109,13 +136,12 @@ export const testMcpServer = new MCPServer({
 
 To make an MCP server available to other systems or agents that support the protocol, register it in the main `Mastra` instance using `mcpServers`.
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 
 import { testMcpServer } from "./mcp/test-mcp-server";
 
 export const mastra = new Mastra({
-  // ...
   mcpServers: {
     testMcpServer,  // Registry key: 'testMcpServer'
   },
@@ -141,9 +167,13 @@ mastra.getMCPServerById('test-mcp-server');    // By intrinsic ID
 
 Use the `.listTools()` method to fetch tools from all configured MCP servers. This is suitable when configuration (such as API keys) is static and consistent across users or requests. Call it once and pass the result to the `tools` property when defining your agent.
 
-> See [listTools()](/reference/v1/tools/mcp-client#listtools) for more information.
+:::info
 
-```typescript {7} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
+Visit [listTools()](/reference/v1/tools/mcp-client#listtools) for more information.
+
+:::
+
+```typescript {7} title="src/mastra/agents/test-agent.ts"
 import { Agent } from "@mastra/core/agent";
 
 import { testMcpClient } from "../mcp/test-mcp-client";
@@ -158,7 +188,7 @@ export const testAgent = new Agent({
 
 Use the `.listToolsets()` method when tool configuration may vary by request or user, such as in a multi-tenant system where each user provides their own API key. This method returns toolsets that can be passed to the `toolsets` option in the agent's `.generate()` or `.stream()` calls.
 
-```typescript {5-16,21} showLineNumbers copy
+```typescript {5-16,21}
 import { MCPClient } from "@mastra/mcp";
 import { mastra } from "./mastra";
 
@@ -190,7 +220,11 @@ async function handleRequest(userPrompt: string, userApiKey: string) {
 }
 ```
 
-> See [listToolsets()](/reference/v1/tools/mcp-client#listtoolsets) for more information.
+:::info
+
+Visit [listToolsets()](/reference/v1/tools/mcp-client#listtoolsets) for more information.
+
+:::
 
 ## Connecting to an MCP registry
 

package/.docs/raw/tools-mcp/overview.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Using Tools | Tools & MCP"
 description: Understand what tools are in Mastra, how to add them to agents, and best practices for designing effective tools.
+packages:
+  - "@mastra/core"
 ---
 
 # Using Tools
@@ -18,7 +20,7 @@ Each tool typically defines:
 
 In Mastra, you create tools using the [`createTool`](/reference/v1/tools/create-tool) function from the `@mastra/core/tools` package.
 
-```typescript title="src/mastra/tools/weatherInfo.ts" copy
+```typescript title="src/mastra/tools/weatherInfo.ts"
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 
@@ -56,32 +58,31 @@ To make tools available to an agent, you configure them in the agent's definitio
 
 ## Using `RequestContext`
 
-Use [RequestContext](/docs/v1/server-db/request-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
+Use [RequestContext](/docs/v1/server/request-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
 
-```typescript title="src/mastra/tools/test-tool.ts" showLineNumbers
+```typescript title="src/mastra/tools/test-tool.ts"
 export type UserTier = {
   "user-tier": "enterprise" | "pro";
 };
 
-const advancedTools = () => {
-  // ...
-};
+const advancedTools = () => {};
 
-const baseTools = () => {
-  // ...
-};
+const baseTools = () => {};
 
 export const testTool = createTool({
-  // ...
-  execute: async ({ requestContext }) => {
-    const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
+  execute: async (inputData, context) => {
+    const userTier = context?.requestContext?.get("user-tier") as UserTier["user-tier"];
 
     return userTier === "enterprise" ? advancedTools : baseTools;
   },
 });
 ```
 
-> See [Request Context](/docs/v1/server-db/request-context) for more information.
+:::info
+
+Visit [Request Context](/docs/v1/server/request-context) for more information.
+
+:::
 
 ## Testing with Studio
 

package/.docs/raw/voice/overview.mdx

@@ -1,6 +1,21 @@
 ---
 title: "Voice in Mastra | Voice"
 description: Overview of voice capabilities in Mastra, including text-to-speech, speech-to-text, and real-time speech-to-speech interactions.
+packages:
+  - "@mastra/core"
+  - "@mastra/node-audio"
+  - "@mastra/voice-azure"
+  - "@mastra/voice-cloudflare"
+  - "@mastra/voice-deepgram"
+  - "@mastra/voice-elevenlabs"
+  - "@mastra/voice-google"
+  - "@mastra/voice-google-gemini-live"
+  - "@mastra/voice-murf"
+  - "@mastra/voice-openai"
+  - "@mastra/voice-openai-realtime"
+  - "@mastra/voice-playai"
+  - "@mastra/voice-sarvam"
+  - "@mastra/voice-speechify"
 ---
 
 import { AudioPlayback } from "@site/src/components/AudioPlayback";
@@ -917,7 +932,7 @@ const voiceAgent = 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"),
+  model: "openai/gpt-5.1",
   voice,
 });
 ```
@@ -1031,4 +1046,4 @@ For more information on the CompositeVoice, refer to the [CompositeVoice Referen
 - [Google Gemini Live Voice](/reference/v1/voice/google-gemini-live)
 - [Deepgram Voice](/reference/v1/voice/deepgram)
 - [PlayAI Voice](/reference/v1/voice/playai)
-- [Voice Examples](/examples/v1/voice/text-to-speech)
+- [Voice Examples](https://github.com/mastra-ai/voice-examples)

package/.docs/raw/voice/speech-to-speech.mdx

@@ -1,6 +1,11 @@
 ---
 title: "Speech-to-Speech Capabilities in Mastra | Voice"
 description: Overview of speech-to-speech capabilities in Mastra, including real-time interactions and event-driven architecture.
+packages:
+  - "@mastra/core"
+  - "@mastra/node-audio"
+  - "@mastra/voice-google-gemini-live"
+  - "@mastra/voice-openai-realtime"
 ---
 
 # Speech-to-Speech Capabilities in Mastra

package/.docs/raw/voice/speech-to-text.mdx

@@ -1,6 +1,10 @@
 ---
 title: "Speech-to-Text (STT) | Voice"
 description: Overview of Speech-to-Text capabilities in Mastra, including configuration, usage, and integration with voice providers.
+packages:
+  - "@mastra/core"
+  - "@mastra/node-audio"
+  - "@mastra/voice-openai"
 ---
 
 # Speech-to-Text (STT)

package/.docs/raw/voice/text-to-speech.mdx

@@ -1,6 +1,9 @@
 ---
 title: "Text-to-Speech (TTS) | Voice"
 description: Overview of Text-to-Speech capabilities in Mastra, including configuration, usage, and integration with voice providers.
+packages:
+  - "@mastra/core"
+  - "@mastra/voice-openai"
 ---
 
 # Text-to-Speech (TTS)