@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.13

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

@@ -1,6 +1,6 @@
 ---
 title: "Agent Approval | Agents"
-description: Learn how to require approvals and suspend tool execution while keeping humans in control of agent workflows.
+description: Learn how to require approvals, suspend tool execution, and automatically resume suspended tools while keeping humans in control of agent workflows.
 ---
 
 # Agent Approval
@@ -180,10 +180,144 @@ const handleResume = async () => {
 
 ```
 
+## Automatic tool resumption
+
+When using tools that call `suspend()`, you can enable automatic resumption so the agent resumes suspended tools based on the user's next message. This creates a conversational flow where users provide the required information naturally, without your application needing to call `resumeStream()` explicitly.
+
+### Enabling auto-resume
+
+Set `autoResumeSuspendedTools` to `true` in the agent's default options or when calling `stream()`:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+
+// Option 1: In agent configuration
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "openai/gpt-4o-mini",
+  tools: { weatherTool },
+  memory: new Memory(),
+  defaultOptions: {
+    autoResumeSuspendedTools: true,
+  },
+});
+
+// Option 2: Per-request
+const stream = await agent.stream("What's the weather?", {
+  autoResumeSuspendedTools: true,
+});
+```
+
+### How it works
+
+When `autoResumeSuspendedTools` is enabled:
+
+1. A tool suspends execution by calling `suspend()` with a payload (e.g., requesting more information)
+2. The suspension is persisted to memory along with the conversation
+3. When the user sends their next message on the same thread, the agent:
+   - Detects the suspended tool from conversation history
+   - Extracts `resumeData` from the user's message based on the tool's `resumeSchema`
+   - Automatically resumes the tool with the extracted data
+
+### Example
+
+```typescript
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const weatherTool = createTool({
+  id: "weather-info",
+  description: "Fetches weather information for a city",
+  suspendSchema: z.object({
+    message: z.string(),
+  }),
+  resumeSchema: z.object({
+    city: z.string(),
+  }),
+  execute: async (_inputData, context) => {
+    // Check if this is a resume with data
+    if (!context?.agent?.resumeData) {
+      // First call - suspend and ask for the city
+      return context?.agent?.suspend({
+        message: "What city do you want to know the weather for?",
+      });
+    }
+
+    // Resume call - city was extracted from user's message
+    const { city } = context.agent.resumeData;
+    const response = await fetch(`https://wttr.in/${city}?format=3`);
+    const weather = await response.text();
+
+    return { city, weather };
+  },
+});
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "openai/gpt-4o-mini",
+  tools: { weatherTool },
+  memory: new Memory(),
+  defaultOptions: {
+    autoResumeSuspendedTools: true,
+  },
+});
+
+const stream = await agent.stream("What's the weather like?");
+
+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.stream("San Francisco");
+
+  for await (const chunk of resumedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+```
+
+**Conversation flow:**
+
+```
+User: "What's the weather like?"
+Agent: "What city do you want to know the weather for?"
+
+User: "San Francisco"
+Agent: "The weather in San Francisco is: San Francisco: ☀️ +72°F"
+```
+
+The second message automatically resumes the suspended tool - the agent extracts `{ city: "San Francisco" }` from the user's message and passes it as `resumeData`.
+
+### Requirements
+
+For automatic tool resumption to work:
+
+- **Memory configured**: The agent needs memory to track suspended tools across messages
+- **Same thread**: The follow-up message must use the same memory thread and resource identifiers
+- **`resumeSchema` defined**: The tool must define a `resumeSchema` so the agent knows what data structure to extract from the user's message
+
+### Manual vs automatic resumption
+
+| Approach | Use case |
+|----------|----------|
+| Manual (`resumeStream()`) | Programmatic control, webhooks, button clicks, external triggers |
+| Automatic (`autoResumeSuspendedTools`) | Conversational flows where users provide resume data in natural language |
+
+Both approaches work with the same tool definitions. Automatic resumption triggers only when suspended tools exist in the conversation history and the user sends a new message on the same thread.
+
 ## Related
 
 - [Using Tools](./using-tools)
 - [Agent Overview](./overview)
 - [Tools Overview](../mcp/overview)
 - [Agent Memory](./agent-memory)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

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

@@ -26,7 +26,7 @@ npm install @mastra/memory@beta @mastra/libsql@beta
 
 ## Storage providers
 
-Memory requires a storage provider to persist conversation history, including user messages and agent responses. For more details on available providers and how storage works in Mastra, see the [Storage](/docs/v1/server-db/storage) documentation.
+Memory requires a storage provider to persist conversation history, including user messages and agent responses. For more details on available providers and how storage works in Mastra, see the [Storage](/docs/v1/memory/storage/overview) documentation.
 
 ## Configuring memory
 
@@ -141,7 +141,7 @@ To learn more about memory see the [Memory](../memory/overview) documentation.
 
 ## Using `RequestContext`
 
-Use [RequestContext](/docs/v1/server-db/request-context) to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.
+Use [RequestContext](/docs/v1/server/request-context) to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.
 
 ```typescript title="src/mastra/agents/memory-agent.ts" showLineNumbers
 export type UserTier = {
@@ -170,7 +170,7 @@ export const memoryAgent = new Agent({
 
 :::note
 
-See [Request Context](/docs/v1/server-db/request-context) docs for more information.
+See [Request Context](/docs/v1/server/request-context) docs for more information.
 
 :::
 
@@ -179,4 +179,4 @@ See [Request Context](/docs/v1/server-db/request-context) docs for more informat
 - [Working Memory](../memory/working-memory)
 - [Semantic Recall](../memory/semantic-recall)
 - [Threads and Resources](../memory/threads-and-resources)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

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

@@ -195,7 +195,7 @@ 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.
+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/mastra-server#stream-data-redaction) for details.
 :::
 
 ## Hybrid processors

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

@@ -239,5 +239,5 @@ network-execution-event-step-finish
 
 - [Agent Memory](./agent-memory)
 - [Workflows Overview](../workflows/overview)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)
 - [Supervisor example](https://github.com/mastra-ai/mastra/tree/main/examples/supervisor-agent)

package/.docs/raw/agents/overview.mdx

@@ -306,7 +306,7 @@ export const testAgent = new Agent({
 });
 ```
 
-> See [Request Context](/docs/v1/server-db/request-context) for more information.
+> See [Request Context](/docs/v1/server/request-context) for more information.
 
 ## Testing with Studio
 
@@ -316,4 +316,4 @@ Use [Studio](/docs/v1/getting-started/studio) to test agents with different mess
 
 - [Using Tools](/docs/v1/agents/using-tools)
 - [Agent Memory](/docs/v1/agents/agent-memory)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/agents/using-tools.mdx

@@ -94,4 +94,4 @@ export const weatherAgent = new Agent({
 
 - [MCP Overview](/docs/v1/mcp/overview)
 - [Agent Memory](/docs/v1/agents/agent-memory)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/course/01-first-agent/07-creating-your-agent.md

@@ -8,7 +8,6 @@ Now add the necessary imports at the top of your file:
 
 ```typescript
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 // We'll import our tool in a later step
 ```
 
@@ -43,7 +42,7 @@ SUCCESS CRITERIA
 - Deliver accurate and helpful analysis of transaction data.
 - Achieve high user satisfaction through clear and helpful responses.
 - Maintain user trust by ensuring data privacy and security.`,
-  model: openai("gpt-4o"), // You can use "gpt-3.5-turbo" if you prefer
+  model: "openai/gpt-4.1-mini",
   tools: {}, // We'll add tools in a later step
 });
 ```

package/.docs/raw/course/01-first-agent/12-connecting-tool-to-agent.md

@@ -19,7 +19,7 @@ export const financialAgent = new Agent({
   TOOLS
   - Use the getTransactions tool to fetch financial transaction data.
   - Analyze the transaction data to answer user questions about their spending.`,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   tools: { getTransactionsTool }, // Add our tool here
 });
 ```

package/.docs/raw/course/01-first-agent/16-adding-memory-to-agent.md

@@ -6,7 +6,6 @@ Now, let's update our agent to include memory. Open your `agents/index.ts` file
 
 ```typescript
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
 import { getTransactionsTool } from "../tools";
@@ -20,7 +19,7 @@ export const financialAgent = new Agent({
   instructions: `ROLE DEFINITION
   // ... existing instructions ...
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   tools: { getTransactionsTool },
   memory: new Memory({
     storage: new LibSQLStore({

package/.docs/raw/course/02-agent-tools-mcp/05-updating-your-agent.md

@@ -10,7 +10,7 @@ export const personalAssistantAgent = new Agent({
     
     Keep your responses concise and friendly.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   tools: { ...mcpTools }, // Add MCP tools to your agent
 });
 ```

package/.docs/raw/course/02-agent-tools-mcp/10-updating-agent-instructions-zapier.md

@@ -18,7 +18,7 @@ export const personalAssistantAgent = new Agent({
     
     Keep your responses concise and friendly.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   tools: { ...mcpTools },
   memory,
 });

package/.docs/raw/course/02-agent-tools-mcp/16-updating-agent-instructions-github.md

@@ -22,7 +22,7 @@ export const personalAssistantAgent = new Agent({
     
     Keep your responses concise and friendly.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   tools: { ...mcpTools },
   memory,
 });

package/.docs/raw/course/02-agent-tools-mcp/21-updating-agent-instructions-hackernews.md

@@ -27,7 +27,7 @@ export const personalAssistantAgent = new Agent({
     
     Keep your responses concise and friendly.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   tools: { ...mcpTools },
   memory,
 });

package/.docs/raw/course/02-agent-tools-mcp/27-updating-agent-instructions-filesystem.md

@@ -34,7 +34,7 @@ export const personalAssistantAgent = new Agent({
     
     Keep your responses concise and friendly.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   tools: { ...mcpTools },
   memory,
 });

package/.docs/raw/course/02-agent-tools-mcp/31-enhancing-memory-configuration.md

@@ -14,7 +14,7 @@ const memory = new Memory({
     id: "learning-memory-vector",
     connectionUrl: "file:../../memory.db",
   }),
-  embedder: openai.embedding("text-embedding-3-small"),
+  embedder: "openai/text-embedding-3-small",
   options: {
     // Keep last 20 messages in context
     lastMessages: 20,
@@ -61,7 +61,7 @@ export const personalAssistantAgent = new Agent({
     Always maintain a helpful and professional tone.
     Use the stored information to provide more personalized responses.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   tools: { ...mcpTools },
   memory,
 });

package/.docs/raw/course/03-agent-memory/04-creating-basic-memory-agent.md

@@ -8,7 +8,6 @@ Create or update your `src/mastra/agents/index.ts` file:
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
-import { openai } from "@ai-sdk/openai";
 
 // Create a basic memory instance
 const memory = new Memory({
@@ -27,7 +26,7 @@ export const memoryAgent = new Agent({
     When a user shares information about themselves, acknowledge it and remember it for future reference.
     If asked about something mentioned earlier in the conversation, recall it accurately.
   `,
-  model: openai("gpt-4o"), // You can use "gpt-3.5-turbo" if you prefer
+  model: "openai/gpt-4.1-mini",
   memory: memory,
 });
 ```

package/.docs/raw/course/03-agent-memory/08-configuring-conversation-history.md

@@ -5,7 +5,6 @@ By default, the `Memory` instance includes the last 10 messages from the current
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore } from "@mastra/libsql";
 
 // Create a memory instance with custom conversation history settings
@@ -27,7 +26,7 @@ export const memoryAgent = new Agent({
     When a user shares information about themselves, acknowledge it and remember it for future reference.
     If asked about something mentioned earlier in the conversation, recall it accurately.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   memory: memory,
 });
 ```

package/.docs/raw/course/03-agent-memory/16-configuring-semantic-recall.md

@@ -5,7 +5,6 @@ Let's update our agent with custom semantic recall settings:
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
 // Create a memory instance with semantic recall configuration
@@ -18,7 +17,7 @@ const memory = new Memory({
     id: "learning-memory-vector",
     connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
   }), // Vector database for semantic search
-  embedder: openai.embedding("text-embedding-3-small"), // Embedder for message embeddings
+  embedder: "openai/text-embedding-3-small", // Embedder for message embeddings
   options: {
     lastMessages: 20, // Include the last 20 messages in the context
     semanticRecall: true, // Enable semantic recall with default settings
@@ -35,9 +34,9 @@ export const memoryAgent = new Agent({
     If asked about something mentioned earlier in the conversation, recall it accurately.
     You can also recall relevant information from older conversations when appropriate.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   memory: memory,
 });
 ```
 
-For semantic recall to work, you need to have a **vector store** configured. You also need to have an **embedder** configured. You may use any `@ai-sdk`-compatible embedding model for this. In this example, we're using OpenAI's `text-embedding-3-small` model.
+For semantic recall to work, you need to have a **vector store** configured. You also need to have an **embedder** configured. You may use any compatible embedding model for this. In this example, we're using OpenAI's `openai/text-embedding-3-small` model.

package/.docs/raw/course/03-agent-memory/21-configuring-working-memory.md

@@ -5,7 +5,6 @@ Let's update our agent with working memory capabilities:
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
 // Create a memory instance with working memory configuration
@@ -18,7 +17,7 @@ const memory = new Memory({
     id: "learning-memory-vector",
     connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
   }), // Vector database for semantic search
-  embedder: openai.embedding("text-embedding-3-small"), // Embedder for message embeddings
+  embedder: "openai/text-embedding-3-small", // Embedder for message embeddings
   options: {
     semanticRecall: {
       topK: 3,
@@ -52,7 +51,7 @@ export const memoryAgent = new Agent({
     Always refer to your working memory before asking for information the user has already provided.
     Use the information in your working memory to provide personalized responses.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   memory: memory,
 });
 ```

package/.docs/raw/course/03-agent-memory/22-custom-working-memory-templates.md

@@ -7,7 +7,6 @@ Let's update our agent with a custom working memory template:
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 
 // Create a memory instance with a custom working memory template
 const memory = new Memory({
@@ -18,7 +17,7 @@ const memory = new Memory({
   vector: new LibSQLVector({
     connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
   }), // Vector database for semantic search
-  embedder: openai.embedding("text-embedding-3-small"), // Embedder for message embeddings
+  embedder: "openai/text-embedding-3-small", // Embedder for message embeddings
   options: {
     semanticRecall: {
       topK: 3,
@@ -74,7 +73,7 @@ export const memoryAgent = new Agent({
     When the user shares personal information such as their name, location, or preferences,
     acknowledge it and update your working memory accordingly.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   memory: memory,
 });
 ```

package/.docs/raw/course/03-agent-memory/25-combining-memory-features.md

@@ -10,7 +10,6 @@ Let's create a comprehensive agent that utilizes conversation history, semantic
 // src/mastra/agents/memory-agent.ts
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
 // Create a comprehensive memory configuration
@@ -22,7 +21,7 @@ const memory = new Memory({
   vector: new LibSQLVector({
     connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
   }),
-  embedder: openai.embedding("text-embedding-3-small"),
+  embedder: "openai/text-embedding-3-small",
   options: {
     // Conversation history configuration
     lastMessages: 20, // Include the last 20 messages in the context

package/.docs/raw/course/03-agent-memory/27-creating-learning-assistant.md

@@ -6,7 +6,6 @@ Let's create a practical example of a memory-enhanced agent: a Personal Learning
 // src/mastra/agents/learning-assistant.ts
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
 // Create a specialized memory configuration for the learning assistant
@@ -18,7 +17,7 @@ const learningMemory = new Memory({
   vector: new LibSQLVector({
     connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
   }),
-  embedder: openai.embedding("text-embedding-3-small"),
+  embedder: "openai/text-embedding-3-small",
   options: {
     lastMessages: 20,
     semanticRecall: {
@@ -88,7 +87,7 @@ export const learningAssistantAgent = new Agent({
     Always be encouraging and supportive. Focus on building the user's confidence
     and celebrating their progress.
   `,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4.1-mini",
   memory: learningMemory,
 });
 

package/.docs/raw/course/04-workflows/11-creating-an-ai-agent.md

@@ -8,7 +8,6 @@ Create a new file for your agent in the `src/mastra/agents` directory. Use `cont
 
 ```typescript
 // src/mastra/agents/content-agent.ts
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 
 export const contentAgent = new Agent({
@@ -23,7 +22,7 @@ export const contentAgent = new Agent({
     
     Always provide constructive, actionable feedback.
   `,
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-4.1-mini",
 });
 ```
 
@@ -32,7 +31,7 @@ export const contentAgent = new Agent({
 - **Name**: Unique identifier for the agent
 - **Description**: What the agent does
 - **Instructions**: Detailed prompts that guide the AI's behavior
-- **Model**: Which AI model to use (GPT-4o-mini is fast and cost-effective)
+- **Model**: Which AI model to use (GPT-4.1-mini is fast and cost-effective)
 
 ## Registering and Testing Your Agent
 

package/.docs/raw/deployment/cloud-providers.mdx

@@ -0,0 +1,20 @@
+---
+title: "Deploy to Cloud Providers | Deployment"
+description: Deploy your Mastra applications to cloud providers
+---
+
+# Deploy to Cloud Providers
+
+Mastra applications can be deployed to cloud providers and serverless platforms. Mastra includes optional built-in deployers for Vercel, Netlify, and Cloudflare to automate the deployment process.
+
+## Supported Cloud Providers
+
+The following guides show how to deploy Mastra to specific cloud providers:
+
+- [Amazon EC2](/guides/v1/deployment/amazon-ec2)
+- [AWS Lambda](/guides/v1/deployment/aws-lambda)
+- [Azure App Services](/guides/v1/deployment/azure-app-services)
+- [Cloudflare](/guides/v1/deployment/cloudflare-deployer)
+- [Digital Ocean](/guides/v1/deployment/digital-ocean)
+- [Netlify](/guides/v1/deployment/netlify-deployer)
+- [Vercel](/guides/v1/deployment/vercel-deployer)

package/.docs/raw/deployment/{building-mastra.mdx → mastra-server.mdx}

@@ -1,9 +1,9 @@
 ---
-title: "Building Mastra | Deployment"
+title: "Deploy a Mastra Server | Deployment"
 description: "Learn how to build a Mastra server with build settings and deployment options."
 ---
 
-# Building Mastra
+# Deploy a Mastra Server
 
 Mastra runs as a standard Node.js server and can be deployed across a wide range of environments.
 

package/.docs/raw/deployment/monorepo.mdx

@@ -1,11 +1,25 @@
 ---
-title: "Monorepo Deployment | Deployment"
+title: "Deploy in a Monorepo | Deployment"
 description: Learn how to deploy Mastra applications that are part of a monorepo setup
 ---
 
-# Monorepo Deployment
+# Deploy in a Monorepo
 
-Deploying Mastra in a monorepo follows the same approach as deploying a standalone application. While some [Cloud](./cloud-providers/) or [Serverless Platform](./cloud-providers/) providers may introduce extra requirements, the core setup is the same.
+Deploying Mastra in a monorepo follows the same approach as deploying a standalone application. While some [Cloud](/guides/v1/deployment) or [Serverless Platform](/guides/v1/deployment) providers may introduce extra requirements, the core setup is the same.
+
+## Supported monorepos
+
+Mastra works with:
+
+- npm workspaces
+- pnpm workspaces
+- Yarn workspaces
+- Turborepo
+
+Known limitations:
+
+- Bun workspaces - partial support; known issues
+- Nx - You can use Nx's [supported dependency strategies](https://nx.dev/concepts/decisions/dependency-management) but you need to have `package.json` files inside your workspace packages
 
 ## Example monorepo
 
@@ -44,10 +58,15 @@ api/
 
 ## Deployment configuration
 
-The image below shows how to select `apps/api` as the project root when deploying to [Mastra Cloud](./mastra-cloud/overview). While the interface may differ between providers, the configuration remains the same.
+The image below shows how to select `apps/api` as the project root when deploying to [Mastra Cloud](/docs/v1/mastra-cloud/overview). While the interface may differ between providers, the configuration remains the same.
 
 ![Deployment configuration](/img/monorepo/monorepo-mastra-cloud.jpg)
 
+
+:::info
+Make sure the correct package (e.g. `apps/api`) is selected as the deploy target. Selecting the wrong project root is a common deployment issue in monorepos.
+:::
+
 ## Dependency management
 
 In a monorepo, keep dependencies consistent to avoid version conflicts and build errors.
@@ -55,43 +74,3 @@ In a monorepo, keep dependencies consistent to avoid version conflicts and build
 - Use a **single lockfile** at the project root so all packages resolve the same versions.
 - Align versions of **shared libraries** (like Mastra or frameworks) to prevent duplicates.
 
-## Deployment pitfalls
-
-Common issues to watch for when deploying Mastra in a monorepo:
-
-- **Wrong project root**: make sure the correct package (e.g. `apps/api`) is selected as the deploy target.
-
-## Bundler options
-
-Use `transpilePackages` to compile TypeScript workspace packages or libraries. List package names exactly as they appear in each `package.json`. Use `externals` to exclude dependencies resolved at runtime, and `sourcemap` to emit readable stack traces.
-
-```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core";
-
-export const mastra = new Mastra({
-  // ...
-  bundler: {
-    transpilePackages: ["utils"],
-    externals: ["ui"],
-    sourcemap: true,
-  },
-});
-```
-
-> See [Mastra Class](/reference/v1/core/mastra-class) for more configuration options.
-
-## Supported monorepos
-
-Mastra works with:
-
-- npm workspaces
-- pnpm workspaces
-- Yarn workspaces
-- Turborepo
-
-Known limitations:
-
-- Bun workspaces — partial support; known issues
-- Nx — You can use Nx's [supported dependency strategies](https://nx.dev/concepts/decisions/dependency-management) but you need to have `package.json` files inside your workspace packages
-
-> If you are experiencing issues with monorepos see our: [Monorepos Support mega issue](https://github.com/mastra-ai/mastra/issues/6852).