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

package/.docs/raw/agents/structured-output.mdx

@@ -0,0 +1,224 @@
+---
+title: "Structured Output | Agents"
+description: "Learn how to generate structured data from agents using schemas and validation."
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Structured Output
+
+Structured output lets an agent return an object that matches the shape defined by a schema instead of returning text. The schema tells the model what fields to produce, and the model ensures the final result fits that shape.
+
+## When to use structured output
+
+Use structured output when you need an agent to return a data object rather than text. Having well defined fields can make it simpler to pull out the values you need for API calls, UI rendering, or application logic.
+
+## Defining schemas
+
+Agents can return structured data by defining the expected output with either [Zod](https://zod.dev/) or [JSON Schema](https://json-schema.org/). Zod is recommended because it provides TypeScript type inference and runtime validation, while JSON Schema is useful when you need a language agnostic format.
+
+<Tabs>
+  <TabItem value="zod" label="Zod">
+
+Define the `output` shape using [Zod](https://zod.dev/):
+
+```typescript showLineNumbers copy
+import { z } from "zod";
+
+const response = await testAgent.generate("Help me plan my day.", {
+  structuredOutput: {
+    schema: z.array(
+      z.object({
+        name: z.string(),
+        activities: z.array(z.string()),
+      }),
+    ),
+  },
+});
+
+console.log(response.object);
+```
+
+  </TabItem>
+  <TabItem value="json-schema" label="JSON Schema">
+
+You can also use JSON Schema to define your output structure:
+
+```typescript showLineNumbers copy
+const response = await testAgent.generate("Help me plan my day.", {
+  structuredOutput: {
+    schema: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          activities: {
+            type: "array",
+            items: { type: "string" },
+          },
+        },
+        required: ["name", "activities"],
+      },
+    },
+  },
+});
+
+console.log(response.object);
+```
+
+  </TabItem>
+</Tabs>
+
+
+> See [.generate()](/reference/v1/agents/generate#structuredoutput) for a full list of configuration options.
+
+### Example output
+
+The `response.object` will contain the structured data as defined by the schema.
+
+```json
+[
+  {
+    "name": "Morning Routine",
+    "activities": ["Wake up at 7am", "Exercise", "Shower", "Breakfast"]
+  },
+  {
+    "name": "Work",
+    "activities": ["Check emails", "Team meeting", "Lunch break"]
+  },
+  {
+    "name": "Evening",
+    "activities": ["Dinner", "Relax", "Read a book", "Sleep by 10pm"]
+  }
+]
+```
+
+## Streaming
+
+Streaming also supports structured output. The final structured object is available on `stream.fullStream` and after the stream completes on `stream.object`. Text stream chunks are still emitted, but they contain natural language text rather than structured data.
+
+```typescript showLineNumbers copy
+import { z } from "zod";
+
+const stream = await testAgent.stream("Help me plan my day.", {
+  structuredOutput: {
+    schema: z.array(
+      z.object({
+        name: z.string(),
+        activities: z.array(z.string())
+      })
+    ),
+  },
+});
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === "object-result") {
+    console.log("\n", JSON.stringify(chunk, null, 2));
+  }
+  process.stdout.write(JSON.stringify(chunk));
+}
+
+console.log(await stream.object)
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+## Structuring agent
+
+When your main agent isn't proficient at creating structured output you can provide a `model` to `structuredOutput`. In this case, Mastra uses a second agent under the hood to extract structured data from the main agent's natural language response. This makes two LLM calls, one to generate the response and another to turn that response into the structured object, which adds some latency and cost but can improve accuracy for complex structuring tasks.
+
+```typescript showLineNumbers copy
+import { z } from "zod";
+
+const response = await testAgent.generate("Analyze the TypeScript programming language.", {
+  structuredOutput: {
+    schema: z.object({
+      overview: z.string(),
+      strengths: z.array(z.string()),
+      weaknesses: z.array(z.string()),
+      useCases: z.array(z.object({
+        scenario: z.string(),
+        reasoning: z.string(),
+      })),
+      comparison: z.object({
+        similarTo: z.array(z.string()),
+        differentiators: z.array(z.string()),
+      }),
+    }),
+    model: "openai/gpt-4o",
+  },
+});
+
+console.log(response.object);
+```
+
+## Response format
+
+By default, Mastra passes the schema to the model provider using the `response_format` API parameter. Most model providers have built-in support for this, which reliably enforces the schema.
+
+If your model provider doesn't support `response_format`, you'll get an error from the API. When this happens, set `jsonPromptInjection: true`. This adds the schema to the system prompt instead, instructing the model to output JSON. This is less reliable than the API parameter approach.
+
+```typescript showLineNumbers copy
+import { z } from "zod";
+
+const response = await testAgent.generate("Help me plan my day.", {
+  structuredOutput: {
+    schema: z.array(
+      z.object({
+        name: z.string(),
+        activities: z.array(z.string()),
+      }),
+    ),
+    jsonPromptInjection: true,
+  },
+});
+
+console.log(response.object);
+```
+
+:::info[Gemini 2.5 with tools]
+
+Gemini 2.5 models do not support combining `response_format` (structured output) with function calling (tools) in the same API call. If your agent has tools and you're using `structuredOutput` with a Gemini 2.5 model, you must set `jsonPromptInjection: true` to avoid the error `Function calling with a response mime type: 'application/json' is unsupported`.
+
+```typescript
+const response = await agentWithTools.generate("Your prompt", {
+  structuredOutput: {
+    schema: yourSchema,
+    jsonPromptInjection: true,  // Required for Gemini 2.5 when tools are present
+  },
+});
+```
+:::
+
+## Error handling
+
+When schema validation fails, you can control how errors are handled using `errorStrategy`. The default `strict` strategy throws an error, while `warn` logs a warning and continues. The `fallback` strategy returns the values provided using `fallbackValue`.
+
+```typescript showLineNumbers copy
+import { z } from "zod";
+
+const response = await testAgent.generate("Tell me about TypeScript.", {
+  structuredOutput: {
+    schema: z.object({
+      summary: z.string(),
+      keyFeatures: z.array(z.string())
+    }),
+    errorStrategy: "fallback",
+    fallbackValue: {
+      summary: "TypeScript is a typed superset of JavaScript",
+      keyFeatures: ["Static typing", "Compiles to JavaScript", "Better tooling"]
+    }
+  }
+});
+
+console.log(response.object);
+```
+
+## Related
+
+- [Using Tools](/docs/v1/agents/using-tools)
+- [Agent Memory](/docs/v1/agents/agent-memory)

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

@@ -1,11 +1,11 @@
 ---
-title: "Using Tools | Agents | Mastra Docs"
+title: "Using Tools | Agents"
 description: Learn how to create tools and add them to agents to extend capabilities beyond text generation.
 ---
 
 # Using Tools
 
-Agents use tools to call APIs, query databases, or run custom functions from your codebase. [Tools](../tools-mcp/overview) give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](../tools-mcp/mcp-overview) to expand an agent’s capabilities.
+Agents use tools to call APIs, query databases, or run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](/docs/v1/mcp/overview) to expand an agent's capabilities.
 
 ## When to use tools
 
@@ -13,6 +13,8 @@ Use tools when an agent needs additional context or information from remote reso
 
 ## Creating a tool
 
+When creating tools, keep descriptions simple and focused on what the tool does, emphasizing its primary use case. Descriptive schema names can also help guide the agent on how to use the tool.
+
 This example shows how to create a tool that fetches weather data from an API. When the agent calls the tool, it provides the required input as defined by the tool's `inputSchema`. The tool accesses this data through its `inputData` parameter, which in this example includes the `location` used in the weather API query.
 
 ```typescript {14} title="src/mastra/tools/weather-tool.ts" showLineNumbers copy
@@ -41,10 +43,11 @@ export const weatherTool = createTool({
 
 ## Adding tools to an agent
 
-To make a tool available to an agent, add it to the `tools` option and reference it by name in the agent’s instructions.
+To make a tool available to an agent, add it to `tools`. Mentioning available tools and their general purpose in the agent's system prompt helps the agent decide when to call a tool and when not to.
+
+An agent can use multiple tools to handle more complex tasks by delegating specific parts to individual tools. The agent decides which tools to use based on the user's message, the agent's instructions, and the tool descriptions and schemas.
 
-```typescript {9,11} title="src/mastra/agents/weather-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
+```typescript {8,10} title="src/mastra/agents/weather-agent.ts" showLineNumbers copy
 import { Agent } from "@mastra/core/agent";
 import { weatherTool } from "../tools/weather-tool";
 
@@ -54,7 +57,7 @@ export const weatherAgent = new Agent({
   instructions: `
       You are a helpful weather assistant.
       Use the weatherTool to fetch current weather data.`,
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   tools: { weatherTool },
 });
 ```
@@ -63,7 +66,7 @@ export const weatherAgent = new Agent({
 
 The agent uses the tool's `inputSchema` to infer what data the tool expects. In this case, it extracts `London` as the `location` from the message and passes it to the tool's inputData parameter.
 
-```typescript {5} title="src/test-tool.ts" showLineNumbers copy
+```typescript title="src/test-tool.ts" showLineNumbers copy
 import { mastra } from "./mastra";
 
 const agent = mastra.getAgent("weatherAgent");
@@ -73,11 +76,9 @@ const result = await agent.generate("What's the weather in London?");
 
 ## Using multiple tools
 
-An agent can use multiple tools to handle more complex tasks by delegating specific parts to individual tools. The agent decides which tools to use based on the user’s message, the agent’s instructions, and the tool descriptions and schemas.
-
-When multiple tools are available, the agent may choose to use one, several, or none, depending on what’s needed to answer the query.
+When multiple tools are available, the agent may choose to use one, several, or none, depending on what's needed to answer the query.
 
-```typescript {6} title="src/mastra/agents/weather-agent.ts" showLineNumbers copy
+```typescript {8} title="src/mastra/agents/weather-agent.ts" showLineNumbers copy
 import { weatherTool } from "../tools/weather-tool";
 import { activitiesTool } from "../tools/activities-tool";
 
@@ -91,7 +92,6 @@ export const weatherAgent = new Agent({
 
 ## Related
 
-- [Tools Overview](../tools-mcp/overview)
-- [Agent Memory](./agent-memory)
+- [MCP Overview](/docs/v1/mcp/overview)
+- [Agent Memory](/docs/v1/agents/agent-memory)
 - [Request Context](/docs/v1/server-db/request-context)
-- [Calling Agents](/examples/v1/agents/calling-agents)

package/.docs/raw/auth/auth0.mdx

@@ -1,5 +1,5 @@
 ---
-title: "MastraAuthAuth0 Class | Auth | Mastra Docs"
+title: "MastraAuthAuth0 Class | Auth"
 description: "Documentation for the MastraAuthAuth0 class, which authenticates Mastra applications using Auth0 authentication."
 ---
 

package/.docs/raw/auth/clerk.mdx

@@ -1,5 +1,5 @@
 ---
-title: "MastraAuthClerk Class | Auth | Mastra Docs"
+title: "MastraAuthClerk Class | Auth"
 description: "Documentation for the MastraAuthClerk class, which authenticates Mastra applications using Clerk authentication."
 ---
 

package/.docs/raw/auth/firebase.mdx

@@ -1,5 +1,5 @@
 ---
-title: "MastraAuthFirebase Class | Auth | Mastra Docs"
+title: "MastraAuthFirebase Class | Auth"
 description: "Documentation for the MastraAuthFirebase class, which authenticates Mastra applications using Firebase Authentication."
 ---
 

package/.docs/raw/auth/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Auth Overview | Auth | Mastra Docs"
+title: "Auth Overview | Auth"
 description: Learn about different Auth options for your Mastra applications
 ---
 

package/.docs/raw/auth/jwt.mdx

@@ -1,5 +1,5 @@
 ---
-title: "MastraJwtAuth Class | Auth | Mastra Docs"
+title: "MastraJwtAuth Class | Auth"
 description: "Documentation for the MastraJwtAuth class, which authenticates Mastra applications using JSON Web Tokens."
 ---
 

package/.docs/raw/auth/supabase.mdx

@@ -1,5 +1,5 @@
 ---
-title: "MastraAuthSupabase Class | Auth | Mastra Docs"
+title: "MastraAuthSupabase Class | Auth"
 description: "Documentation for the MastraAuthSupabase class, which authenticates Mastra applications using Supabase Auth."
 ---
 

package/.docs/raw/auth/workos.mdx

@@ -1,5 +1,5 @@
 ---
-title: "MastraAuthWorkos Class | Auth | Mastra Docs"
+title: "MastraAuthWorkos Class | Auth"
 description: "Documentation for the MastraAuthWorkos class, which authenticates Mastra applications using WorkOS authentication."
 ---
 

package/.docs/raw/community/contributing-templates.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Contributing Templates | Community | Mastra Docs"
+title: "Contributing Templates | Community"
 description: "How to contribute your own templates to the Mastra ecosystem"
 ---
 

package/.docs/raw/community/discord.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Discord Community | Community | Mastra Docs"
+title: "Discord Community | Community"
 description: Information about the Mastra Discord community and MCP bot.
 ---
 
@@ -9,4 +9,4 @@ The Discord server has over 1000 members and serves as the main discussion forum
 
 ## Discord MCP Bot
 
-In addition to community members, we have an (experimental!) Discord bot that can also help answer questions. It uses [Model Context Protocol (MCP)](/docs/v1/tools-mcp/mcp-overview). You can ask it a question with `/ask` (either in public channels or DMs) and clear history (in DMs only) with `/cleardm`.
+In addition to community members, we have an (experimental!) Discord bot that can also help answer questions. It uses [Model Context Protocol (MCP)](/docs/v1/mcp/overview). You can ask it a question with `/ask` (either in public channels or DMs) and clear history (in DMs only) with `/cleardm`.

package/.docs/raw/community/licensing.mdx

@@ -1,5 +1,5 @@
 ---
-title: "License | Community | Mastra Docs"
+title: "License | Community"
 description: "Mastra License"
 ---
 

package/.docs/raw/course/01-first-agent/05-running-playground.md

@@ -1,14 +1,14 @@
-# Running the Playground
+# Running Mastra Studio
 
-To test your agent as you build it, you'll need to run the Mastra playground:
+To test your agent as you build it, you'll need to run the Mastra Studio:
 
 ```bash
 npm run dev
 ```
 
-This will start the playground at `http://localhost:4111/`, where you can interact with your agent and test its capabilities.
+This will start the studio at `http://localhost:4111`, where you can interact with your agent and test its capabilities.
 
-The playground provides a user-friendly interface for testing your agent, allowing you to:
+The studio provides a user-friendly interface for testing your agent, allowing you to:
 
 - Send messages to your agent
 - See the agent's responses
@@ -16,4 +16,4 @@ The playground provides a user-friendly interface for testing your agent, allowi
 - Test tools directly
 - Debug any issues that arise
 
-In the next step, we'll create our first agent with a simple system prompt and test it in the playground.
+In the next step, we'll create our first agent with a simple system prompt and test it in the studio.

package/.docs/raw/course/01-first-agent/09-testing-your-agent.md

@@ -1,12 +1,12 @@
 # Testing Your Agent
 
-Now let's test our agent in the playground:
+Now let's test our agent in Mastra Studio:
 
 1. Make sure your development server is running with `npm run dev`
-2. Open the playground at http://localhost:4111/
+2. Open the studio at http://localhost:4111/
 3. You should see your "Financial Assistant Agent" in the list of agents
 4. Try sending a message like "Hello, can you help me analyze my spending?"
 
 At this point, your agent can respond to basic questions but doesn't have access to any transaction data. In the next step, we'll create a custom tool to fetch transaction data from a Google Sheet.
 
-Testing your agent in the playground is an important step in the development process. It allows you to see how your agent responds to different inputs and identify any issues that need to be addressed before deploying it to production.
+Testing your agent in the studio is an important step in the development process. It allows you to see how your agent responds to different inputs and identify any issues that need to be addressed before deploying it to production.

package/.docs/raw/course/01-first-agent/13-testing-your-tool.md

@@ -1,9 +1,9 @@
 # Testing Your Tool
 
-Let's test our tool and agent in the playground:
+Let's test our tool and agent in Mastra Studio:
 
 1. Make sure your development server is running with `npm run dev`
-2. Open the playground at http://localhost:4111/
+2. Open the studio at http://localhost:4111/
 3. You can test the tool directly in the Tools tab to make sure it's working
 4. Then, try asking your agent questions like:
    - "Can you show me my recent transactions?"
@@ -12,4 +12,4 @@ Let's test our tool and agent in the playground:
 
 Your agent should now be able to fetch the transaction data and answer questions about it. However, it doesn't yet have memory, so it won't remember previous conversations. We'll add that in the next step.
 
-Testing your tool directly in the playground is a great way to verify that it's working correctly before integrating it with your agent. This helps you identify and fix any issues with the tool itself before troubleshooting potential issues with the agent's use of the tool.
+Testing your tool directly in the studio is a great way to verify that it's working correctly before integrating it with your agent. This helps you identify and fix any issues with the tool itself before troubleshooting potential issues with the agent's use of the tool.

package/.docs/raw/course/01-first-agent/17-testing-memory.md

@@ -1,9 +1,9 @@
 # Testing Your Agent with Memory
 
-Let's test our agent's memory capabilities in the playground:
+Let's test our agent's memory capabilities in Mastra Studio:
 
 1. Make sure your development server is running with `npm run dev`
-2. Open the playground at http://localhost:4111/
+2. Open the studio at http://localhost:4111/
 3. Start a conversation with your agent by asking about transactions
 4. Then, ask a follow-up question that references the previous conversation, like:
    - "What was that largest transaction again?"

package/.docs/raw/course/04-workflows/07-using-playground.md

@@ -14,7 +14,7 @@ You should see output like:
 
 ```bash
 🚀 Mastra Dev Server starting...
-📊 Playground available at: http://localhost:4111
+📊 Studio available at: http://localhost:4111
 ```
 
 ## Accessing Workflows in Playground

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

@@ -1,15 +1,15 @@
 ---
-title: "Deploy a Mastra Server | Deployment | Mastra Docs"
-description: "Learn how to deploy a Mastra server with build settings and deployment options."
+title: "Building Mastra | Deployment"
+description: "Learn how to build a Mastra server with build settings and deployment options."
 ---
 
-# Deploy a Mastra Server
+# Building Mastra
 
 Mastra runs as a standard Node.js server and can be deployed across a wide range of environments.
 
 ## Default project structure
 
-The [getting started guide](/docs/v1/getting-started/installation) scaffolds a project with sensible defaults to help you begin quickly. By default, the CLI organizes application files under the `src/mastra/` directory, resulting in a structure similar to the following:
+The [getting started guide](/guides/v1/getting-started/quickstart) scaffolds a project with sensible defaults to help you begin quickly. By default, the CLI organizes application files under the `src/mastra/` directory, resulting in a structure similar to the following:
 
 ```
 src/

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

@@ -1,5 +1,5 @@
 ---
-title: "Amazon EC2 | Deployment | Mastra Docs"
+title: "Amazon EC2 | Deployment"
 description: "Deploy your Mastra applications to Amazon EC2."
 ---
 
@@ -16,7 +16,7 @@ Deploy your Mastra applications to Amazon EC2 (Elastic Cloud Compute).
 This guide assumes your Mastra application has been created using the default
 `npx create-mastra@beta` command.
 For more information on how to create a new Mastra application,
-refer to our [getting started guide](/docs/v1/getting-started/installation)
+refer to our [getting started guide](/guides/v1/getting-started/quickstart)
 :::
 
 ## Prerequisites

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

@@ -1,5 +1,5 @@
 ---
-title: "AWS Lambda | Deployment | Mastra Docs"
+title: "AWS Lambda | Deployment"
 description: "Deploy your Mastra applications to AWS Lambda using Docker containers and the AWS Lambda Web Adapter."
 ---
 
@@ -15,7 +15,7 @@ This approach allows you to run your Mastra server as a containerized Lambda fun
 This guide assumes your Mastra application has been created using the default
 `npx create-mastra@beta` command.
 For more information on how to create a new Mastra application,
-refer to our [getting started guide](/docs/v1/getting-started/installation)
+refer to our [getting started guide](/guides/v1/getting-started/quickstart)
 :::
 
 ## Prerequisites
@@ -216,7 +216,7 @@ Once deployed, test your Lambda function:
 2. Visit the URL in your browser to see your Mastra's server home screen
 3. Test your agents and workflows using the generated API endpoints
 
-For more information about available API endpoints, see the [Server documentation](/docs/v1/deployment/server-deployment).
+For more information about available API endpoints, see the [Server documentation](/docs/v1/deployment/building-mastra).
 
 ## Connecting your client
 

package/.docs/raw/deployment/cloud-providers/azure-app-services.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Azure App Services | Deployment | Mastra Docs"
+title: "Azure App Services | Deployment"
 description: "Deploy your Mastra applications to Azure App Services."
 ---
 
@@ -14,7 +14,7 @@ Deploy your Mastra applications to Azure App Services.
 This guide assumes your Mastra application has been created using the default
 `npx create-mastra@beta` command.
 For more information on how to create a new Mastra application,
-refer to our [getting started guide](/docs/v1/getting-started/installation)
+refer to our [getting started guide](/guides/v1/getting-started/quickstart)
 :::
 
 ## Prerequisites

package/.docs/raw/deployment/{serverless-platforms → cloud-providers}/cloudflare-deployer.mdx

@@ -1,5 +1,5 @@
 ---
-title: "CloudflareDeployer | Deployment | Mastra Docs"
+title: "CloudflareDeployer | Deployment"
 description: "Learn how to deploy a Mastra application to Cloudflare using the Mastra CloudflareDeployer"
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Digital Ocean | Deployment | Mastra Docs"
+title: "Digital Ocean | Deployment"
 description: "Deploy your Mastra applications to Digital Ocean."
 ---
 
@@ -16,7 +16,7 @@ Deploy your Mastra applications to Digital Ocean's App Platform and Droplets.
 This guide assumes your Mastra application has been created using the default
 `npx create-mastra@beta` command.
 For more information on how to create a new Mastra application,
-refer to our [getting started guide](./../../getting-started/installation)
+refer to our [getting started guide](/guides/v1/getting-started/quickstart)
 :::
 
 <Tabs>