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

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

@@ -48,11 +48,11 @@ export const testMcpClient = new MCPClient({
 });
 ```
 
-> See [MCPClient](/reference/tools/mcp-client) for a full list of configuration options.
+> See [MCPClient](/reference/v1/tools/mcp-client) for a full list of configuration options.
 
 ## Using `MCPClient` with an agent
 
-To use tools from an MCP server in an agent, import your `MCPClient` and call `.getTools()` in the `tools` parameter. This loads from the defined MCP servers, making them available to the 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 {4,16} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
 import { openai } from "@ai-sdk/openai";
@@ -61,6 +61,7 @@ import { Agent } from "@mastra/core/agent";
 import { testMcpClient } from "../mcp/test-mcp-client";
 
 export const testAgent = new Agent({
+  id: "test-agent",
   name: "Test Agent",
   description: "You are a helpful AI assistant",
   instructions: `
@@ -70,11 +71,11 @@ export const testAgent = new Agent({
 
       Answer questions using the information you find using the MCP Servers.`,
   model: openai("gpt-4o-mini"),
-  tools: await testMcpClient.getTools(),
+  tools: await testMcpClient.listTools(),
 });
 ```
 
-> See the [Agent Class](/reference/agents/agent) for a full list of configuration options.
+> See the [Agent Class](/reference/v1/agents/agent) for a full list of configuration options.
 
 ## Configuring `MCPServer`
 
@@ -88,8 +89,8 @@ import { testWorkflow } from "../workflows/test-workflow";
 import { testTool } from "../tools/test-tool";
 
 export const testMcpServer = new MCPServer({
-  id: "test-mcp-server",
-  name: "Test Server",
+  id: "test-mcp-server",  // Required: unique identifier for the server
+  name: "Test MCP Server",
   version: "1.0.0",
   agents: { testAgent },
   tools: { testTool },
@@ -97,28 +98,40 @@ export const testMcpServer = new MCPServer({
 });
 ```
 
-> See [MCPServer](/reference/tools/mcp-server) for a full list of configuration options.
+> See [MCPServer](/reference/v1/tools/mcp-server) for a full list of configuration options.
+
+### Serverless deployments
+
+`MCPServer` can be deployed in serverless environments (Cloudflare Workers, Vercel Edge Functions, AWS Lambda, etc.) by enabling the `serverless: true` option in `startHTTP()`. This runs the server in stateless mode, where each request is handled independently without session management.
+
+**Note:** Some MCP features require persistent connections and won't work in serverless mode, including elicitation, resource subscriptions, and update notifications. See the [serverless section](/reference/v1/tools/mcp-server#starthttp) in the API reference for full details and limitations.
 
 ## Registering an `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
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 
 import { testMcpServer } from "./mcp/test-mcp-server";
 
 export const mastra = new Mastra({
   // ...
-  mcpServers: { testMcpServer },
+  mcpServers: {
+    testMcpServer,  // Registry key: 'testMcpServer'
+  },
 });
+
+// Both retrieval methods work:
+mastra.getMCPServer('testMcpServer');          // By registry key
+mastra.getMCPServerById('test-mcp-server');    // By intrinsic ID
 ```
 
 ## Static and dynamic tools
 
 `MCPClient` offers two approaches to retrieving tools from connected servers, suitable for different application architectures:
 
-| Feature           | Static Configuration (`await mcp.getTools()`) | Dynamic Configuration (`await mcp.getToolsets()`)    |
+| Feature           | Static Configuration (`await mcp.listTools()`) | Dynamic Configuration (`await mcp.listToolsets()`)    |
 | :---------------- | :-------------------------------------------- | :--------------------------------------------------- |
 | **Use Case**      | Single-user, static config (e.g., CLI tool)   | Multi-user, dynamic config (e.g., SaaS app)          |
 | **Configuration** | Fixed at agent initialization                 | Per-request, dynamic                                 |
@@ -127,9 +140,9 @@ export const mastra = new Mastra({
 
 ### Static tools
 
-Use the `.getTools()` 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.
+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 [getTools()](/reference/tools/mcp-client#gettools) for more information.
+> See [listTools()](/reference/v1/tools/mcp-client#listtools) for more information.
 
 ```typescript {8} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
 import { openai } from "@ai-sdk/openai";
@@ -139,13 +152,13 @@ import { testMcpClient } from "../mcp/test-mcp-client";
 
 export const testAgent = new Agent({
   // ...
-  tools: await testMcpClient.getTools(),
+  tools: await testMcpClient.listTools(),
 });
 ```
 
 ### Dynamic tools
 
-Use the `.getToolsets()` 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.
+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
 import { MCPClient } from "@mastra/mcp";
@@ -168,7 +181,7 @@ async function handleRequest(userPrompt: string, userApiKey: string) {
   const agent = mastra.getAgent("testAgent");
 
   const response = await agent.generate(userPrompt, {
-    toolsets: await userMcp.getToolsets(),
+    toolsets: await userMcp.listToolsets(),
   });
 
   await userMcp.disconnect();
@@ -179,7 +192,7 @@ async function handleRequest(userPrompt: string, userApiKey: string) {
 }
 ```
 
-> See [getToolsets()](/reference/tools/mcp-client#gettoolsets) for more information.
+> See [listToolsets()](/reference/v1/tools/mcp-client#listtoolsets) for more information.
 
 ## Connecting to an MCP registry
 
@@ -355,6 +368,6 @@ As an alternative to MCP, Ampersand's AI SDK also has an adapter for Mastra, so
 
 ## Related
 
-- [Using Tools](/docs/agents/using-tools)
-- [MCPClient](/reference/tools/mcp-client)
-- [MCPServer](/reference/tools/mcp-server)
+- [Using Tools](/docs/v1/agents/using-tools)
+- [MCPClient](/reference/v1/tools/mcp-client)
+- [MCPServer](/reference/v1/tools/mcp-server)

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

@@ -16,7 +16,7 @@ Each tool typically defines:
 
 ## Creating Tools
 
-In Mastra, you create tools using the [`createTool`](/reference/tools/create-tool) function from the `@mastra/core/tools` package.
+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
 import { createTool } from "@mastra/core/tools";
@@ -39,9 +39,9 @@ export const weatherTool = createTool({
     temperature: z.number(),
     conditions: z.string(),
   }),
-  execute: async ({ context: { city } }) => {
-    console.log("Using tool to fetch weather information for", city);
-    return await getWeatherInfo(city);
+  execute: async (inputData) => {
+    console.log("Using tool to fetch weather information for", inputData.city);
+    return await getWeatherInfo(inputData.city);
   },
 });
 ```
@@ -52,11 +52,11 @@ When creating tools, keep tool descriptions simple and focused on **what** the t
 
 ## Adding Tools to an Agent
 
-To make tools available to an agent, you configure them in the agent's definition. Mentioning available tools and their general purpose in the agent's system prompt can also improve tool usage. For detailed steps and examples, see the guide on [Using Tools with Agents](/docs/agents/using-tools#adding-tools-to-an-agent).
+To make tools available to an agent, you configure them in the agent's definition. Mentioning available tools and their general purpose in the agent's system prompt can also improve tool usage. For detailed steps and examples, see the guide on [Using Tools with Agents](/docs/v1/agents/using-tools#adding-tools-to-an-agent).
 
-## Using `RuntimeContext`
+## Using `RequestContext`
 
-Use [RuntimeContext](/docs/server-db/runtime-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
+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.
 
 ```typescript title="src/mastra/tools/test-tool.ts" showLineNumbers
 export type UserTier = {
@@ -73,16 +73,16 @@ const baseTools = () => {
 
 export const testTool = createTool({
   // ...
-  execute: async ({ runtimeContext }) => {
-    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
+  execute: async ({ requestContext }) => {
+    const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
 
     return userTier === "enterprise" ? advancedTools : baseTools;
   },
 });
 ```
 
-> See [Runtime Context](/docs/server-db/runtime-context) for more information.
+> See [Request Context](/docs/v1/server-db/request-context) for more information.
 
 ## Testing with Studio
 
-Use [Studio](/docs/getting-started/studio) to test tools with different inputs, inspect execution results, and verify tool behavior.
+Use [Studio](/docs/v1/getting-started/studio) to test tools with different inputs, inspect execution results, and verify tool behavior.

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

@@ -13,7 +13,7 @@ Mastra's Voice system provides a unified interface for voice interactions, enabl
 
 ## Adding Voice to Agents
 
-To learn how to integrate voice capabilities into your agents, check out the [Adding Voice to Agents](/docs/agents/adding-voice) documentation. This section covers how to use both single and multiple voice providers, as well as real-time interactions.
+To learn how to integrate voice capabilities into your agents, check out the [Adding Voice to Agents](/docs/v1/agents/adding-voice) documentation. This section covers how to use both single and multiple voice providers, as well as real-time interactions.
 
 ```typescript
 import { Agent } from "@mastra/core/agent";
@@ -23,6 +23,7 @@ import { OpenAIVoice } from "@mastra/voice-openai";
 // Initialize OpenAI voice for TTS
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -50,6 +51,7 @@ import { OpenAIVoice } from "@mastra/voice-openai";
 import { playAudio } from "@mastra/node-audio";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -68,7 +70,7 @@ const audioStream = await voiceAgent.voice.speak(text, {
 playAudio(audioStream);
 ```
 
-Visit the [OpenAI Voice Reference](/reference/voice/openai) for more information on the OpenAI voice provider.
+Visit the [OpenAI Voice Reference](/reference/v1/voice/openai) for more information on the OpenAI voice provider.
 
   </TabItem>
   <TabItem value="azure" label="Azure">
@@ -80,6 +82,7 @@ import { AzureVoice } from "@mastra/voice-azure";
 import { playAudio } from "@mastra/node-audio";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -97,7 +100,7 @@ const audioStream = await voiceAgent.voice.speak(text, {
 playAudio(audioStream);
 ```
 
-Visit the [Azure Voice Reference](/reference/voice/azure) for more information on the Azure voice provider.
+Visit the [Azure Voice Reference](/reference/v1/voice/azure) for more information on the Azure voice provider.
 
   </TabItem>
   <TabItem value="elevenlabs" label="ElevenLabs">
@@ -109,6 +112,7 @@ import { ElevenLabsVoice } from "@mastra/voice-elevenlabs";
 import { playAudio } from "@mastra/node-audio";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -126,7 +130,7 @@ const audioStream = await voiceAgent.voice.speak(text, {
 playAudio(audioStream);
 ```
 
-Visit the [ElevenLabs Voice Reference](/reference/voice/elevenlabs) for more information on the ElevenLabs voice provider.
+Visit the [ElevenLabs Voice Reference](/reference/v1/voice/elevenlabs) for more information on the ElevenLabs voice provider.
 
   </TabItem>
   <TabItem value="playai" label="PlayAI">
@@ -138,6 +142,7 @@ import { PlayAIVoice } from "@mastra/voice-playai";
 import { playAudio } from "@mastra/node-audio";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -155,7 +160,7 @@ const audioStream = await voiceAgent.voice.speak(text, {
 playAudio(audioStream);
 ```
 
-Visit the [PlayAI Voice Reference](/reference/voice/playai) for more information on the PlayAI voice provider.
+Visit the [PlayAI Voice Reference](/reference/v1/voice/playai) for more information on the PlayAI voice provider.
 
   </TabItem>
   <TabItem value="google" label="Google">
@@ -167,6 +172,7 @@ import { GoogleVoice } from "@mastra/voice-google";
 import { playAudio } from "@mastra/node-audio";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -184,7 +190,7 @@ const audioStream = await voiceAgent.voice.speak(text, {
 playAudio(audioStream);
 ```
 
-Visit the [Google Voice Reference](/reference/voice/google) for more information on the Google voice provider.
+Visit the [Google Voice Reference](/reference/v1/voice/google) for more information on the Google voice provider.
 
   </TabItem>
   <TabItem value="cloudflare" label="Cloudflare">
@@ -196,6 +202,7 @@ import { CloudflareVoice } from "@mastra/voice-cloudflare";
 import { playAudio } from "@mastra/node-audio";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -213,7 +220,7 @@ const audioStream = await voiceAgent.voice.speak(text, {
 playAudio(audioStream);
 ```
 
-Visit the [Cloudflare Voice Reference](/reference/voice/cloudflare) for more information on the Cloudflare voice provider.
+Visit the [Cloudflare Voice Reference](/reference/v1/voice/cloudflare) for more information on the Cloudflare voice provider.
 
   </TabItem>
   <TabItem value="deepgram" label="Deepgram">
@@ -225,6 +232,7 @@ import { DeepgramVoice } from "@mastra/voice-deepgram";
 import { playAudio } from "@mastra/node-audio";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -242,7 +250,7 @@ const audioStream = await voiceAgent.voice.speak(text, {
 playAudio(audioStream);
 ```
 
-Visit the [Deepgram Voice Reference](/reference/voice/deepgram) for more information on the Deepgram voice provider.
+Visit the [Deepgram Voice Reference](/reference/v1/voice/deepgram) for more information on the Deepgram voice provider.
 
   </TabItem>
   <TabItem value="speechify" label="Speechify">
@@ -254,6 +262,7 @@ import { SpeechifyVoice } from "@mastra/voice-speechify";
 import { playAudio } from "@mastra/node-audio";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -271,7 +280,7 @@ const audioStream = await voiceAgent.voice.speak(text, {
 playAudio(audioStream);
 ```
 
-Visit the [Speechify Voice Reference](/reference/voice/speechify) for more information on the Speechify voice provider.
+Visit the [Speechify Voice Reference](/reference/v1/voice/speechify) for more information on the Speechify voice provider.
 
   </TabItem>
   <TabItem value="sarvam" label="Sarvam">
@@ -283,6 +292,7 @@ import { SarvamVoice } from "@mastra/voice-sarvam";
 import { playAudio } from "@mastra/node-audio";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -300,7 +310,7 @@ const audioStream = await voiceAgent.voice.speak(text, {
 playAudio(audioStream);
 ```
 
-Visit the [Sarvam Voice Reference](/reference/voice/sarvam) for more information on the Sarvam voice provider.
+Visit the [Sarvam Voice Reference](/reference/v1/voice/sarvam) for more information on the Sarvam voice provider.
 
   </TabItem>
   <TabItem value="murf" label="Murf">
@@ -312,6 +322,7 @@ import { MurfVoice } from "@mastra/voice-murf";
 import { playAudio } from "@mastra/node-audio";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -329,7 +340,7 @@ const audioStream = await voiceAgent.voice.speak(text, {
 playAudio(audioStream);
 ```
 
-Visit the [Murf Voice Reference](/reference/voice/murf) for more information on the Murf voice provider.
+Visit the [Murf Voice Reference](/reference/v1/voice/murf) for more information on the Murf voice provider.
 
   </TabItem>
 </Tabs>
@@ -353,6 +364,7 @@ import { OpenAIVoice } from "@mastra/voice-openai";
 import { createReadStream } from "fs";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -371,7 +383,7 @@ console.log(`User said: ${transcript}`);
 const { text } = await voiceAgent.generate(transcript);
 ```
 
-Visit the [OpenAI Voice Reference](/reference/voice/openai) for more information on the OpenAI voice provider.
+Visit the [OpenAI Voice Reference](/reference/v1/voice/openai) for more information on the OpenAI voice provider.
 
   </TabItem>
   <TabItem value="azure" label="Azure">
@@ -384,6 +396,7 @@ import { AzureVoice } from "@mastra/voice-azure";
 import { createReadStream } from "fs";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -402,7 +415,7 @@ console.log(`User said: ${transcript}`);
 const { text } = await voiceAgent.generate(transcript);
 ```
 
-Visit the [Azure Voice Reference](/reference/voice/azure) for more information on the Azure voice provider.
+Visit the [Azure Voice Reference](/reference/v1/voice/azure) for more information on the Azure voice provider.
 
   </TabItem>
   <TabItem value="elevenlabs" label="ElevenLabs">
@@ -414,6 +427,7 @@ import { ElevenLabsVoice } from "@mastra/voice-elevenlabs";
 import { createReadStream } from "fs";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -432,7 +446,7 @@ console.log(`User said: ${transcript}`);
 const { text } = await voiceAgent.generate(transcript);
 ```
 
-Visit the [ElevenLabs Voice Reference](/reference/voice/elevenlabs) for more information on the ElevenLabs voice provider.
+Visit the [ElevenLabs Voice Reference](/reference/v1/voice/elevenlabs) for more information on the ElevenLabs voice provider.
 
   </TabItem>
   <TabItem value="google" label="Google">
@@ -444,6 +458,7 @@ import { GoogleVoice } from "@mastra/voice-google";
 import { createReadStream } from "fs";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -462,7 +477,7 @@ console.log(`User said: ${transcript}`);
 const { text } = await voiceAgent.generate(transcript);
 ```
 
-Visit the [Google Voice Reference](/reference/voice/google) for more information on the Google voice provider.
+Visit the [Google Voice Reference](/reference/v1/voice/google) for more information on the Google voice provider.
 
   </TabItem>
   <TabItem value="cloudflare" label="Cloudflare">
@@ -474,6 +489,7 @@ import { CloudflareVoice } from "@mastra/voice-cloudflare";
 import { createReadStream } from "fs";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -492,7 +508,7 @@ console.log(`User said: ${transcript}`);
 const { text } = await voiceAgent.generate(transcript);
 ```
 
-Visit the [Cloudflare Voice Reference](/reference/voice/cloudflare) for more information on the Cloudflare voice provider.
+Visit the [Cloudflare Voice Reference](/reference/v1/voice/cloudflare) for more information on the Cloudflare voice provider.
 
   </TabItem>
   <TabItem value="deepgram" label="Deepgram">
@@ -504,6 +520,7 @@ import { DeepgramVoice } from "@mastra/voice-deepgram";
 import { createReadStream } from "fs";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -522,7 +539,7 @@ console.log(`User said: ${transcript}`);
 const { text } = await voiceAgent.generate(transcript);
 ```
 
-Visit the [Deepgram Voice Reference](/reference/voice/deepgram) for more information on the Deepgram voice provider.
+Visit the [Deepgram Voice Reference](/reference/v1/voice/deepgram) for more information on the Deepgram voice provider.
 
   </TabItem>
   <TabItem value="sarvam" label="Sarvam">
@@ -534,6 +551,7 @@ import { SarvamVoice } from "@mastra/voice-sarvam";
 import { createReadStream } from "fs";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -552,7 +570,7 @@ console.log(`User said: ${transcript}`);
 const { text } = await voiceAgent.generate(transcript);
 ```
 
-Visit the [Sarvam Voice Reference](/reference/voice/sarvam) for more information on the Sarvam voice provider.
+Visit the [Sarvam Voice Reference](/reference/v1/voice/sarvam) for more information on the Sarvam voice provider.
 
   </TabItem>
 </Tabs>
@@ -572,6 +590,7 @@ import { playAudio, getMicrophoneStream } from "@mastra/node-audio";
 import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -592,7 +611,7 @@ const micStream = getMicrophoneStream();
 await voiceAgent.voice.send(micStream);
 ```
 
-Visit the [OpenAI Voice Reference](/reference/voice/openai-realtime) for more information on the OpenAI voice provider.
+Visit the [OpenAI Voice Reference](/reference/v1/voice/openai-realtime) for more information on the OpenAI voice provider.
 
   </TabItem>
   <TabItem value="google" label="Google">
@@ -604,6 +623,7 @@ import { playAudio, getMicrophoneStream } from "@mastra/node-audio";
 import { GeminiLiveVoice } from "@mastra/voice-google-gemini-live";
 
 const voiceAgent = new Agent({
+  id: "voice-agent",
   name: "Voice Agent",
   instructions:
     "You are a voice assistant that can help users with their tasks.",
@@ -643,7 +663,7 @@ const micStream = getMicrophoneStream();
 await voiceAgent.voice.send(micStream);
 ```
 
-Visit the [Google Gemini Live Reference](/reference/voice/google-gemini-live) for more information on the Google Gemini Live voice provider.
+Visit the [Google Gemini Live Reference](/reference/v1/voice/google-gemini-live) for more information on the Google Gemini Live voice provider.
 
   </TabItem>
 </Tabs>
@@ -674,7 +694,7 @@ const voice = new OpenAIVoice({
 });
 ```
 
-Visit the [OpenAI Voice Reference](/reference/voice/openai) for more information on the OpenAI voice provider.
+Visit the [OpenAI Voice Reference](/reference/v1/voice/openai) for more information on the OpenAI voice provider.
 
   </TabItem>
   <TabItem value="azure" label="Azure">
@@ -700,7 +720,7 @@ const voice = new AzureVoice({
 });
 ```
 
-Visit the [Azure Voice Reference](/reference/voice/azure) for more information on the Azure voice provider.
+Visit the [Azure Voice Reference](/reference/v1/voice/azure) for more information on the Azure voice provider.
 
   </TabItem>
   <TabItem value="elevenlabs" label="ElevenLabs">
@@ -719,7 +739,7 @@ const voice = new ElevenLabsVoice({
 });
 ```
 
-Visit the [ElevenLabs Voice Reference](/reference/voice/elevenlabs) for more information on the ElevenLabs voice provider.
+Visit the [ElevenLabs Voice Reference](/reference/v1/voice/elevenlabs) for more information on the ElevenLabs voice provider.
 
   </TabItem>
   <TabItem value="playai" label="PlayAI">
@@ -738,7 +758,7 @@ const voice = new PlayAIVoice({
 });
 ```
 
-Visit the [PlayAI Voice Reference](/reference/voice/playai) for more information on the PlayAI voice provider.
+Visit the [PlayAI Voice Reference](/reference/v1/voice/playai) for more information on the PlayAI voice provider.
 
   </TabItem>
   <TabItem value="google" label="Google">
@@ -760,7 +780,7 @@ const voice = new GoogleVoice({
 });
 ```
 
-Visit the [Google Voice Reference](/reference/voice/google) for more information on the Google voice provider.
+Visit the [Google Voice Reference](/reference/v1/voice/google) for more information on the Google voice provider.
 
   </TabItem>
   <TabItem value="cloudflare" label="Cloudflare">
@@ -779,7 +799,7 @@ const voice = new CloudflareVoice({
 });
 ```
 
-Visit the [Cloudflare Voice Reference](/reference/voice/cloudflare) for more information on the Cloudflare voice provider.
+Visit the [Cloudflare Voice Reference](/reference/v1/voice/cloudflare) for more information on the Cloudflare voice provider.
 
   </TabItem>
   <TabItem value="deepgram" label="Deepgram">
@@ -801,7 +821,7 @@ const voice = new DeepgramVoice({
 });
 ```
 
-Visit the [Deepgram Voice Reference](/reference/voice/deepgram) for more information on the Deepgram voice provider.
+Visit the [Deepgram Voice Reference](/reference/v1/voice/deepgram) for more information on the Deepgram voice provider.
 
   </TabItem>
   <TabItem value="speechify" label="Speechify">
@@ -820,7 +840,7 @@ const voice = new SpeechifyVoice({
 });
 ```
 
-Visit the [Speechify Voice Reference](/reference/voice/speechify) for more information on the Speechify voice provider.
+Visit the [Speechify Voice Reference](/reference/v1/voice/speechify) for more information on the Speechify voice provider.
 
   </TabItem>
   <TabItem value="sarvam" label="Sarvam">
@@ -838,7 +858,7 @@ const voice = new SarvamVoice({
 });
 ```
 
-Visit the [Sarvam Voice Reference](/reference/voice/sarvam) for more information on the Sarvam voice provider.
+Visit the [Sarvam Voice Reference](/reference/v1/voice/sarvam) for more information on the Sarvam voice provider.
 
   </TabItem>
   <TabItem value="murf" label="Murf">
@@ -856,7 +876,7 @@ const voice = new MurfVoice({
 });
 ```
 
-Visit the [Murf Voice Reference](/reference/voice/murf) for more information on the Murf voice provider.
+Visit the [Murf Voice Reference](/reference/v1/voice/murf) for more information on the Murf voice provider.
 
   </TabItem>
   <TabItem value="openai-realtime" label="OpenAI Realtime">
@@ -878,7 +898,7 @@ const voice = new OpenAIRealtimeVoice({
 });
 ```
 
-For more information on the OpenAI Realtime voice provider, refer to the [OpenAI Realtime Voice Reference](/reference/voice/openai-realtime).
+For more information on the OpenAI Realtime voice provider, refer to the [OpenAI Realtime Voice Reference](/reference/v1/voice/openai-realtime).
 
   </TabItem>
   <TabItem value="google-gemini-live" label="Google Gemini Live">
@@ -895,7 +915,7 @@ const voice = new GeminiLiveVoice({
 });
 ```
 
-Visit the [Google Gemini Live Reference](/reference/voice/google-gemini-live) for more information on the Google Gemini Live voice provider.
+Visit the [Google Gemini Live Reference](/reference/v1/voice/google-gemini-live) for more information on the Google Gemini Live voice provider.
 
   </TabItem>
 </Tabs>
@@ -951,17 +971,17 @@ const responseAudio = await voice.speak(`You said: ${transcript}`, {
 playAudio(responseAudio);
 ```
 
-For more information on the CompositeVoice, refer to the [CompositeVoice Reference](/reference/voice/composite-voice).
+For more information on the CompositeVoice, refer to the [CompositeVoice Reference](/reference/v1/voice/composite-voice).
 
 ## More Resources
 
-- [CompositeVoice](/reference/voice/composite-voice)
-- [MastraVoice](/reference/voice/mastra-voice)
-- [OpenAI Voice](/reference/voice/openai)
-- [OpenAI Realtime Voice](/reference/voice/openai-realtime)
-- [Azure Voice](/reference/voice/azure)
-- [Google Voice](/reference/voice/google)
-- [Google Gemini Live Voice](/reference/voice/google-gemini-live)
-- [Deepgram Voice](/reference/voice/deepgram)
-- [PlayAI Voice](/reference/voice/playai)
-- [Voice Examples](/examples/voice/text-to-speech)
+- [CompositeVoice](/reference/v1/voice/composite-voice)
+- [MastraVoice](/reference/v1/voice/mastra-voice)
+- [OpenAI Voice](/reference/v1/voice/openai)
+- [OpenAI Realtime Voice](/reference/v1/voice/openai-realtime)
+- [Azure Voice](/reference/v1/voice/azure)
+- [Google Voice](/reference/v1/voice/google)
+- [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)