@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.6

package/.docs/raw/guides/index.mdx

@@ -1,43 +1,11 @@
 ---
 title: "Overview"
 description: "Guides on building with Mastra"
+showCopyButton: false
 ---
 
 import { CardGrid, CardGridItem } from "@site/src/components/CardGrid";
 
-# Guides
+# Mastra Guides
 
-While examples show quick implementations and docs explain specific features, these guides are a bit longer and designed to demonstrate core Mastra concepts:
-
-<CardGrid>
-  <CardGridItem
-    title="AI Recruiter"
-    description="Create a workflow that processes candidate resumes and conducts interviews, demonstrating branching logic and LLM integration in Mastra workflows."
-    href="/guides/v1/guide/ai-recruiter"
-  />
-  <CardGridItem
-    title="Chef Assistant"
-    description="Build an AI chef agent that helps users cook meals with available ingredients, showing how to create interactive agents with custom tools."
-    href="/guides/v1/guide/chef-michel"
-  />
-  <CardGridItem
-    title="Research Assistant"
-    description="Develop an AI research assistant that analyzes academic papers using Retrieval Augmented Generation (RAG), demonstrating document processing and question answering."
-    href="/guides/v1/guide/research-assistant"
-  />
-  <CardGridItem
-    title="Stock Agent"
-    description="Implement a simple agent that fetches stock prices, illustrating the basics of creating tools and integrating them with Mastra agents."
-    href="/guides/v1/guide/stock-agent"
-  />
-  <CardGridItem
-    title="Notes MCP Server"
-    description="Build an AI notes assistant that helps users manage their notes, showing how to create interactive agents with custom tools."
-    href="/guides/v1/guide/notes-mcp-server"
-  />
-  <CardGridItem
-    title="Web Search"
-    description="A step-by-step guide to creating an agent that can search the web."
-    href="/guides/v1/guide/web-search"
-  />
-</CardGrid>
+Mastra offers a variety of guides to help you build and work with Mastra, from building agents and workflows to using the Mastra SDK and API, and implementing different UI frameworks. To find what you need, use the left-hand side navigation to browse by topic or use the search bar to look up specific implementation details, frameworks, or features.

package/.docs/raw/guides/migrations/agentnetwork.mdx

@@ -40,7 +40,7 @@ const agent = new AgentNetwork({
   name: "agent-network",
   agents: [agent1, agent2],
   tools: { tool1, tool2 },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
 });
@@ -61,7 +61,7 @@ const agent = new Agent({
   name: "agent-network",
   agents: { agent1, agent2 },
   tools: { tool1, tool2 },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
   memory,
@@ -83,7 +83,7 @@ const agent = new NewAgentNetwork({
   agents: { agent1, agent2 },
   workflows: { workflow1 },
   tools: { tool1, tool2 },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
 });
@@ -104,7 +104,7 @@ const agent = new Agent({
   agents: { agent1, agent2 },
   workflows: { workflow1 },
   tools: { tool1, tool2 },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
   memory,

package/.docs/raw/guides/migrations/ai-sdk-v4-to-v5.mdx

@@ -5,7 +5,7 @@ description: "Mastra-specific guidance for upgrading from AI SDK v4 to v5."
 
 # Migrate from AI SDK v4 to v5
 
-Looking for integration docs? See [Using AI SDK](/docs/v1/frameworks/agentic-uis/ai-sdk).
+Looking for integration docs? See [Using AI SDK](/guides/v1/build-your-ui/ai-sdk-ui).
 
 Follow the official [AI SDK v5 Migration Guide](https://v5.ai-sdk.dev/docs/migration-guides/migration-guide-5-0) for all AI SDK core breaking changes, package updates, and API changes.
 

package/.docs/raw/guides/migrations/upgrade-to-v1/agent.mdx

@@ -202,6 +202,46 @@ To migrate, update from `output` or `experimental_output` to `structuredOutput.s
   });
 ```
 
+### Agent `id` field is now required
+
+The `id` field is now required when creating an Agent. Previously, agents could be created without an explicit ID, but this is no longer supported.
+
+To migrate, add an `id` field to all Agent configurations.
+
+```diff
+  const agent = new Agent({
++   id: 'my-agent',
+    name: 'My Agent',
+    instructions: 'You are a helpful assistant',
+    model: openai('gpt-4'),
+  });
+```
+
+The `id` can be the same as the `name`, or you can use a different identifier. The ID will be used when calling `mastra.getAgentById()` and must be unique within your Mastra instance.
+
+```typescript
+// Register agent with Mastra
+const mastra = new Mastra({
+  agents: {
+    myAgent: agent, // key can differ from id
+  },
+});
+
+// Retrieve by ID
+const agent = mastra.getAgentById('my-agent');
+```
+
+### Stream API responses now redact sensitive data
+
+The Mastra server now automatically redacts sensitive information from agent stream responses. This prevents accidental exposure of system prompts, tool definitions, and API keys in `step-start`, `step-finish`, and `finish` stream chunks.
+
+**What's redacted:**
+- `request.body` containing LLM request payloads (system prompts, tool schemas)
+- `metadata.request` in step results
+- `output.steps[].request` in nested step data
+
+This behavior is enabled by default. If you need access to the full request data (e.g., for debugging or internal services), you can disable redaction when using server adapters directly (e.g., `@mastra/hono` or `@mastra/express`).
+
 ## Removed
 
 ### `generateVNext` and `streamVNext` methods

package/.docs/raw/guides/migrations/upgrade-to-v1/tools.mdx

@@ -83,6 +83,11 @@ For tools that are executed inside a workflow, access workflow-specific properti
   });
 ```
 
+The `suspendPayload` gets validated against the `suspendSchema` when the tool is executed. If the suspendPayload doesn't match the `suspendSchema`, a warning is logged and the error is returned as tool output, but suspension continues.
+Also, when the tool is resumed, the `resumeData` gets validated against the `resumeSchema`. If the resumeData doesn't match the `resumeSchema`, the tool will return a `ValidationError`, preventing the tool resumption.
+
+To skip the `suspendSchema` or `resumeSchema` validation, do not define `suspendSchema` or `resumeSchema` in the tool creation.
+
 :::note
 For MCP-specific tool context changes, see the [MCP migration guide](/guides/v1/migrations/upgrade-to-v1/mcp).
 :::

package/.docs/raw/guides/migrations/upgrade-to-v1/workflows.mdx

@@ -136,8 +136,59 @@ createWorkflow({
 })
 ```
 
+### Step `suspendPayload` validation
+
+Step `suspendPayload` is now validated for steps that have a `suspendSchema` defined. This also uses the `validateInputs` flag to determine whether to validate the `suspendPayload` or not.
+
+```diff
+  createStep({
+    id: "suspend-resume-step",
+    // ... other step properties
+    suspendSchema: z.object({
+      reason: z.string(),
+      otherReason: z.string()
+    }),
+    execute: async ({ suspend, resumeData}) => {
+      if (!resumeData) {
+-       return suspend({ reason: "Suspension reason" }); // Missing otherReason
++       return suspend({ reason: "Suspension reason", otherReason: "Other reason" });
+      }
+      //... continue execution logic
+    },
+  });
+```
+
+### Branch result fields are now optional
+
+The `.branch()` method now returns a schema where all branch output fields are optional. This reflects the runtime behavior where each branch only executes if its condition is truthy, so outputs from any branch may be undefined.
+
+To migrate, update any code that consumes branch outputs to handle optional values.
+
+```diff
+  const workflow = createWorkflow({...})
+    .branch([
+      [condition1, stepA],  // outputSchema: { result: z.string() }
+      [condition2, stepB],  // outputSchema: { data: z.number() }
+    ])
+-   // Previously: stepA.result typed as string, stepB.data typed as number
++   // Now: stepA.result typed as string | undefined, stepB.data typed as number | undefined
+    .then(nextStep);
+```
+
+If your code depends on non-optional types, add runtime checks or provide default values when accessing branch outputs.
+
+See [Run.resumeStream()](/reference/v1/streaming/workflows/resumeStream) for details.
+
 ## Removed
 
+### `streamVNext`, `resumeStreamVNext`, and `observeStreamVNext` methods
+
+The experimental `streamVNext()`, `resumeStreamVNext()`, and `observeStreamVNext()` methods have been removed. These methods are now the standard implementation with updated event structures and return types.
+
+To migrate, use the standard `stream()`, `resumeStream()`, and `observeStream()` methods. Update event type checks to use workflow-prefixed names and access stream properties directly.
+
+See [`Run.stream()`](/reference/v1/streaming/workflows/stream), [`Run.resumeStream()`](/reference/v1/streaming/workflows/resumeStream), and [`Run.observeStream()`](/reference/v1/streaming/workflows/observeStream) for details.
+
 ### Legacy workflows export
 
 The `./workflows/legacy` export path has been removed from `@mastra/core`. Legacy workflows are no longer supported.

package/.docs/raw/guides/migrations/vnext-to-standard-apis.mdx

@@ -160,7 +160,7 @@ The following options are available in the standard `.stream()` and `generate()`
           name: z.string(),
           age: z.number(),
         }),
-        model: "openai/gpt-4o-mini", // Optional model override for structuring
+        model: "openai/gpt-5.1", // Optional model override for structuring
         errorStrategy: "fallback",
         fallbackValue: { name: "unknown", age: 0 },
         instructions: "Extract user information", // Override default structuring instructions
@@ -300,7 +300,7 @@ The following options are available in the standard `.stream()` and `generate()`
       schema: z.object({
         summary: z.string(),
       }),
-      model: "openai/gpt-4o",
+      model: "openai/gpt-5.1",
     },
   });
   ```

package/.docs/raw/index.mdx

@@ -51,8 +51,8 @@ Explore real-world examples in our [community showcase](/showcase).
 
 ## Get started
 
-Choose a [quickstart](/docs/v1/getting-started/quickstart) to get started, or see the [manual installation guide](/guides/v1/guide/manual-install) if you need more control over your setup.
+Choose a [getting started guide](/docs/v1/getting-started/start) to get started, or see the [manual installation guide](/docs/v1/getting-started/manual-install) if you need more control over your setup.
 
-If you're new to AI agents, check out our [templates](/docs/v1/getting-started/templates), [course](https://mastra.ai/course), and [YouTube videos](https://youtube.com/@mastra-ai). You can also join our [Discord](https://discord.gg/BTYqqHKUrf) community to get help and share your projects.
+If you're new to AI agents, check out our [templates](https://mastra.ai/templates), [course](https://mastra.ai/course), and [YouTube videos](https://youtube.com/@mastra-ai). You can also join our [Discord](https://discord.gg/BTYqqHKUrf) community to get help and share your projects.
 
 We can't wait to see what you build ✌️

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

@@ -54,8 +54,7 @@ export const testMcpClient = new MCPClient({
 
 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.
 
-```typescript {4,16} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
+```typescript {3,15} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
 import { Agent } from "@mastra/core/agent";
 
 import { testMcpClient } from "../mcp/test-mcp-client";
@@ -69,7 +68,7 @@ export const testAgent = new Agent({
       - US National Weather Service
 
       Answer questions using the information you find using the MCP Servers.`,
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   tools: await testMcpClient.getTools(),
 });
 ```
@@ -131,8 +130,7 @@ Use the `.getTools()` method to fetch tools from all configured MCP servers. Thi
 
 > See [getTools()](/reference/v1/tools/mcp-client#gettools) for more information.
 
-```typescript {8} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
+```typescript {7} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
 import { Agent } from "@mastra/core/agent";
 
 import { testMcpClient } from "../mcp/test-mcp-client";