@mastra/mcp-docs-server 0.13.11 → 0.13.12-alpha.1

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

@@ -5,47 +5,72 @@ description: Overview of agents in Mastra, detailing their capabilities and how
 
 # Using Agents
 
-**Agents** are one of the core Mastra primitives. Agents use a language model to decide on a sequence of actions. They can call functions (known as _tools_). You can compose them with *workflows* (the other main Mastra primitive), either by giving an agent a workflow as a tool, or by running an agent from within a workflow.
+Agents let you build intelligent assistants powered by language models that can make decisions and perform actions. Each agent has required instructions and an LLM, with optional tools and memory.
 
-Agents can run autonomously in a loop, run once, or take turns with a user. You can give short-term, long-term, and working memory of their user interactions. They can stream text or return structured output (ie, JSON). They can access third-party APIs, query knowledge bases, and so on.
+An agent coordinates conversations, calls tools when needed, maintains context through memory, and produces responses tailored to the interaction. Agents can operate on their own or work as part of larger workflows.
 
-Additionally, agents support dynamic configuration, allowing you to change their instructions, model, tools, and memory based on runtime context like user preferences, subscription tiers, or environment settings.
+![Agents overview](/image/agents/agents-overview.jpg)
 
-## 1. Creating an Agent
+To create an agent:
 
-To create an agent in Mastra, you use the `Agent` class and define its properties:
+- Define **instructions** with the `Agent` class and set the **LLM** it will use.
+- Optionally configure **tools** and **memory** to extend functionality.
+- Run the agent to generate responses, with support for streaming, structured output, and dynamic configuration.
+
+This approach provides type safety and runtime validation, ensuring reliable behavior across all agent interactions.
+
+> **📹 Watch**:  → An introduction to agents, and how they compare to workflows [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
+
+## Getting started
+
+To use agents, install the required dependencies:
+
+```bash
+npm install @mastra/core @ai-sdk/openai
+```
+
+> Mastra works with all AI SDK provider. See [Model Providers](../getting-started/model-providers.mdx) for more information.
+
+Import the necessary class from the agents module, and an LLM provider:
 
 ```typescript filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
 import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
-
-const testAgent = new Agent({
-  name: "test-agent",
-  instructions: "You are a helpful assistant.",
-  model: openai("gpt-4o")
-});
 ```
+### LLM providers
 
-**Note:** Ensure that you have set the necessary environment variables, such as your OpenAI API key, in your `.env` file:
+Each LLM provider needs its own API key, named using the provider’s identifier:
 
 ```bash filename=".env" copy
 OPENAI_API_KEY=<your-api-key>
 ```
 
-Also, make sure you have the `@mastra/core` package installed:
+> See the [AI SDK Providers](https://ai-sdk.dev/providers/ai-sdk-providers) in the Vercel AI SDK docs.
+
+### Creating an agent
+
+To create an agent in Mastra, use the `Agent` class. Every agent must include `instructions` to define its behavior, and a `model` parameter to specify the LLM provider and model:
+
+```typescript filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
 
-```bash npm2yarn copy
-npm install @mastra/core@latest
+export const testAgent = new Agent({
+  name: "test-agent",
+  instructions: "You are a helpful assistant.",
+  model: openai("gpt-4o-mini")
+});
 ```
 
-All agent properties (instructions, model, tools, memory) can be configured dynamically using runtime context. See the [Dynamic Agents guide](./dynamic-agents.mdx) for examples of how to adapt agent behavior based on user context, subscription tiers, or other runtime variables.
+> See [Agent](../../reference/agents/agent.mdx) for more information.
+
 
-### Registering the Agent
+### Registering an agent
 
-Register your agent with Mastra to enable logging and access to configured tools and integrations:
+Register your agent in the Mastra instance:
 
 ```typescript showLineNumbers filename="src/mastra/index.ts" copy
-import { Mastra } from "@mastra/core";
+import { Mastra } from "@mastra/core/mastra";
 import { testAgent } from './agents/test-agent';
 
 export const mastra = new Mastra({
@@ -54,145 +79,111 @@ export const mastra = new Mastra({
 });
 ```
 
-## 2. Generating and streaming text
+## Referencing an agent
+
+You can call agents from workflow steps, tools, the Mastra Client, or the command line. Get a reference by calling `.getAgent()` on your `mastra` or `mastraClient` instance, depending on your setup:
+
+```typescript showLineNumbers copy
+const testAgent = mastra.getAgent("testAgent");
+```
+
+> See [Calling agents](../../examples/agents/calling-agents.mdx) for more information.
+
+## Generating responses
+
+Use `.generate()` to get a response from an agent. Pass a single string for simple prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content` for precise control over roles and conversational flows.
+
+> See [.generate()](../../reference/agents/generate.mdx) for more information.
 
 ### Generating text
 
-Use the `.generate()` method to have your agent produce text responses:
+Call `.generate()` with an array of message objects that include `role` and `content`:
 
 ```typescript showLineNumbers copy
 const response = await testAgent.generate([
-  { role: "user", content: "Hello, how can you assist me today?" },
+  { role: "user", content: "Help me organize my day" },
+  { role: "user", content: "My day starts at 9am and finishes at 5.30pm" },
+  { role: "user", content: "I take lunch between 12:30 and 13:30" },
+  { role: "user", content: "I have meetings Monday to Friday between 10:30 and 11:30" }
 ]);
 
-console.log("Agent:", response.text);
+console.log(response.text);
 ```
 
-For more details about the generate method and its options, see the [generate reference documentation](/reference/agents/generate).
+## Streaming responses
+
+Use `.stream()` for real-time responses. Pass a single string for simple prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content` for precise control over roles and conversational flows.
+
+> See [.stream()](../../reference/agents/stream.mdx) for more information.
 
-### Streaming responses
+### Streaming text
 
-For more real-time responses, you can stream the agent's response:
+Call `.stream()` with an array of message objects that include `role` and `content`:
 
 ```typescript showLineNumbers copy
 const stream = await testAgent.stream([
-  { role: "user", content: "Tell me a story." },
+  { role: "user", content: "Help me organize my day" },
+  { role: "user", content: "My day starts at 9am and finishes at 5.30pm" },
+  { role: "user", content: "I take lunch between 12:30 and 13:30" },
+  { role: "user", content: "I have meetings Monday to Friday between 10:30 and 11:30" }
 ]);
 
-console.log("Agent:");
-
 for await (const chunk of stream.textStream) {
   process.stdout.write(chunk);
 }
 ```
 
-For more details about streaming responses, see the [stream reference documentation](/reference/agents/stream).
-
-## 3. Describing images
+### Completion using `onFinish()`
 
-Agents can analyze and describe images by processing both the visual content and any text within them. To enable image analysis, pass an object with `type: 'image'` and the image URL in the content array. You can combine image content with text prompts to guide the agent's analysis.
+When streaming responses, the `onFinish()` callback runs after the LLM finishes generating its response and all tool executions are complete.
+It provides the final `text`, execution `steps`, `finishReason`, token `usage` statistics, and other metadata useful for monitoring or logging.
 
 ```typescript showLineNumbers copy
-await testAgent.generate([
-  {
-    role: 'user',
-    content: [
-      {
-        type: 'image',
-        image: "https://example.com/images/test-image.jpg",
-        mimeType: "image/jpeg"
-      },
-      {
-        type: 'text',
-        text: 'Describe the image in detail, and extract all the text in the image.',
-      },
-    ],
-  },
-]);
-```
-
-## 4. Structured Output
-
-Agents can return structured data by providing a JSON Schema or using a Zod schema.
-
-### Using JSON Schema
-
-```typescript showLineNumbers copy
-const schema = {
-  type: "object",
-  properties: {
-    summary: { type: "string" },
-    keywords: { type: "array", items: { type: "string" } },
-  },
-  additionalProperties: false,
-  required: ["summary", "keywords"],
-};
-
-const response = await testAgent.generate(
-  [
-    {
-      role: "user",
-      content:
-        "Please provide a summary and keywords for the following text: ...",
-    },
-  ],
-  {
-    output: schema,
-  },
-);
+const stream = await testAgent.stream("Help me organize my day", {
+  onFinish: ({ steps, text, finishReason, usage }) => {
+    console.log({ steps, text, finishReason, usage });
+  }
+});
 
-console.log("Structured Output:", response.object);
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
 ```
 
-### Using Zod
-
-You can also use Zod schemas for type-safe structured outputs.
+## Structured output
 
-First, install Zod:
+Agents can return structured, type-safe data by defining the expected output with either [Zod](https://zod.dev/) or [JSON Schema](https://json-schema.org/). In both cases, the parsed result is available on `response.object`, allowing you to work directly with validated and typed data.
 
-```bash npm2yarn copy
-npm install zod
-```
+### Using Zod
 
-Then, define a Zod schema and use it with the agent:
+Define the `output` shape using [Zod](https://zod.dev/):
 
 ```typescript showLineNumbers copy
 import { z } from "zod";
 
-// Define the Zod schema
-const schema = z.object({
-  summary: z.string(),
-  keywords: z.array(z.string()),
+const response = await testAgent.generate("Monkey, Ice Cream, Boat", {
+  experimental_output: z.object({
+    summary: z.string(),
+    keywords: z.array(z.string())
+  })
 });
 
-// Use the schema with the agent
-const response = await testAgent.generate(
-  [
-    {
-      role: "user",
-      content:
-        "Please provide a summary and keywords for the following text: ...",
-    },
-  ],
-  {
-    output: schema,
-  },
-);
-
-console.log("Structured Output:", response.object);
+console.log(response.object);
 ```
 
 ### Using Tools
 
-If you need to generate structured output alongside tool calls, you'll need to use the `experimental_output` property instead of `output`. Here's how:
+If you need to generate structured output alongside tool calls, you'll need to use the `experimental_output` or `structuredOutput` property instead of `output`. Here's how:
 
 ```typescript showLineNumbers copy
-const schema = z.object({
-  summary: z.string(),
-  keywords: z.array(z.string()),
+const response = await testAgent.generate("Monkey, Ice Cream, Boat", {
+  experimental_output: z.object({
+    summary: z.string(),
+    keywords: z.array(z.string())
+  })
 });
 
-const response = await testAgent.generate(
+const responseWithExperimentalOutput = await testAgent.generate(
   [
     {
       role: "user",
@@ -206,112 +197,98 @@ const response = await testAgent.generate(
   },
 );
 
-console.log("Structured Output:", response.object);
-```
+console.log("Structured Output:", responseWithExperimentalOutput.object);
 
-<br />
-
-This allows you to have strong typing and validation for the structured data returned by the agent.
-
-## 5. Multi-step tool use
-
-Agents can be enhanced with tools - functions that extend their capabilities beyond text generation. Tools allow agents to perform calculations, access external systems, and process data. Agents not only decide whether to call tools they're given, they determine the parameters that should be given to that tool.
-
-For a detailed guide to creating and configuring tools, see the [Adding Tools documentation](/docs/agents/using-tools-and-mcp), but below are the important things to know.
-
-### Using `maxSteps`
-
-The `maxSteps` parameter controls the maximum number of sequential LLM calls an agent can make, particularly important when using tool calls. By default, it is set to 1 to prevent infinite loops in case of misconfigured tools. You can increase this limit based on your use case:
-
-```typescript showLineNumbers copy
-const response = await testAgent.generate(
+const responseWithStructuredOutput = await testAgent.generate(
   [
     {
       role: "user",
       content:
-        "If a taxi driver earns $41 per hour and works 12 hours a day, how much do they earn in one day?",
+        "Please analyze this repository and provide a summary and keywords...",
     },
   ],
   {
-    maxSteps: 5, // Allow up to 5 tool usage steps
+    structuredOutput: {
+      schema: z.object({
+        summary: z.string(),
+        keywords: z.array(z.string())
+      }),
+      model: openai("gpt-4o-mini"),
+    }
   },
 );
-```
 
-### Using `onStepFinish`
+console.log("Structured Output:", responseWithStructuredOutput.object);
+```
 
-You can monitor the progress of multi-step operations using the `onStepFinish` callback. This is useful for debugging or providing progress updates to users.
+## Describing images
 
-`onStepFinish` is only available when streaming or generating text without structured output.
+Agents can analyze and describe images by processing both the visual content and any text within them. To enable image analysis, pass an object with `type: 'image'` and the image URL in the `content` array. You can combine image content with text prompts to guide the agent's analysis.
 
 ```typescript showLineNumbers copy
-const response = await testAgent.generate(
-  [{ role: "user", content: "Calculate the taxi driver's daily earnings." }],
+const response = await testAgent.generate([
   {
-    maxSteps: 5,
-    onStepFinish: ({ text, toolCalls, toolResults }) => {
-      console.log("Step completed:", { text, toolCalls, toolResults });
-    },
-  },
-);
+    role: "user",
+    content: [
+      {
+        type: "image",
+        image: "https://placebear.com/cache/395-205.jpg",
+        mimeType: "image/jpeg"
+      },
+      {
+        type: "text",
+        text: "Describe the image in detail, and extract all the text in the image."
+      }
+    ]
+  }
+]);
+
+console.log(response.text);
 ```
 
-### Streaming steps with `onChunk`
+## Multi-step tool use
+
+Agents can be enhanced with tools, functions that extend their capabilities beyond text generation. Tools allow agents to perform calculations, access external systems, and process data. Agents not only decide whether to call tools they're given, they determine the parameters that should be given to that tool.
 
-You can monitor the progress of multi-step operations using the `onChunk` callback. This is useful for debugging or providing progress updates to users.
+For a detailed guide to creating and configuring tools, see the [Tools Overview](../tools-mcp/overview.mdx) page.
+
+### Using `maxSteps`
+
+The `maxSteps` parameter controls the maximum number of sequential LLM calls an agent can make, particularly important when using tool calls. By default, it is set to 1 to prevent infinite loops in case of misconfigured tools:
 
 ```typescript showLineNumbers copy
-const stream = await testAgent.stream(
-  [{ role: "user", content: "Calculate the taxi driver's daily earnings." }],
-  {
-    maxSteps: 5,
-    onChunk: ({ chunk }) => {
-      console.log("Chunk", chunk);
-    },
-  },
-);
+const response = await testAgent.generate("Help me organize my day", {
+  maxSteps: 5
+});
 
-for await (const chunk of stream.textStream) {
-  console.log(chunk);
-}
+console.log(response.text);
 ```
 
-### Detecting completion with `onFinish`
+### Using `onStepFinish`
 
-The `onFinish` callback is available when streaming responses and provides detailed information about the completed interaction. It is called after the LLM has finished generating its response and all tool executions have completed.
-This callback receives the final response text, execution steps, token usage statistics, and other metadata that can be useful for monitoring and logging:
+You can monitor the progress of multi-step operations using the `onStepFinish` callback. This is useful for debugging or providing progress updates to users.
+
+`onStepFinish` is only available when streaming or generating text without structured output.
 
 ```typescript showLineNumbers copy
-const stream = await testAgent.stream(
-  [{ role: "user", content: "Calculate the taxi driver's daily earnings." }],
-  {
-    maxSteps: 5,
-    onFinish: ({
-      steps,
-      text,
-      finishReason, // 'complete', 'length', 'tool', etc.
-      usage, // token usage statistics
-      reasoningDetails, // additional context about the agent's decisions
-    }) => {
-      console.log("Stream complete:", {
-        totalSteps: steps.length,
-        finishReason,
-        usage,
-      });
-    },
-  },
-);
+const response = await testAgent.generate("Help me organize my day", {
+  onStepFinish: ({ text, toolCalls, toolResults, finishReason, usage }) => {
+    console.log({ text, toolCalls, toolResults, finishReason, usage });
+  }
+});
 ```
 
-## 6. Testing agents locally
+## Testing agents locally
 
-Mastra provides a CLI command `mastra dev` to run your agents behind an API. By default, this looks for exported agents in files in the `src/mastra/agents` directory. It generates endpoints for testing your agent (eg `http://localhost:4111/api/agents/myAgent/generate`) and provides a visual playground where you can chat with an agent and view traces.
+Use the `mastra dev` CLI command to run your agents behind a local API.
+By default, it loads exported agents from the `src/mastra/agents` directory and creates endpoints for testing (for example, `http://localhost:4111/api/agents/myAgent/generate`).
+It also launches a visual playground where you can chat with your agent and view execution traces.
 
-For more details, see the [Local Dev Playground](/docs/server-db/local-dev-playground) docs.
+> For more information, see the [Local Dev Playground](/docs/server-db/local-dev-playground) documentation.
 
 ## Next Steps
 
-- Learn about Agent Memory in the [Agent Memory](./agent-memory.mdx) guide.
-- Learn about Dynamic Agent configuration in the [Dynamic Agents](./dynamic-agents.mdx) guide.
-- Learn about Agent Tools in the [Agent Tools and MCP](./using-tools-and-mcp.mdx) guide.
-- See an example agent in the [Chef Michel](../../guides/guide/chef-michel.mdx) example.
+- [Agent Memory](./agent-memory.mdx)
+- [Dynamic Agents](./dynamic-agents.mdx)
+- [Agent Tools and MCP](./using-tools-and-mcp.mdx)
+- [Calling Agents](../../examples/agents/calling-agents.mdx)

package/.docs/raw/agents/streaming.mdx

@@ -3,13 +3,19 @@ title: "Using Agent Streaming | Agents | Mastra Docs"
 description: Documentation on how to stream agents
 ---
 
+import { Callout } from "nextra/components";
+
 # Agent Streaming
 
-Agents in Mastra have access to a powerful streaming protocol! With seamless integration into tools or agents as a tool, you can stream responses directly back to your clients, creating a more interactive and engaging experience.
+Agents in Mastra support streaming responses for real-time interaction with clients. This enables progressive rendering of responses and better user experience.
+
+<Callout type="info">
+  **Experimental API**: The `streamVNext` method shown in this guide is an experimental feature that will replace the current `stream()` method after additional testing and refinement. For production use, consider using the stable [`stream()` method](/docs/agents/overview#2-generating-and-streaming-text) until `streamVNext` is finalized.
+</Callout>
 
 ## Usage
 
-To use the new protocol, you can use the `streamVNext` method on an agent. This method will return a custom MastraAgentStream. This stream extends a ReadableStream, so all basic stream methods are available.
+The experimental streaming protocol uses the `streamVNext` method on an agent. This method returns a custom MastraAgentStream that extends ReadableStream with additional utilities.
 
 ```typescript
 const stream = await agent.streamVNext({ role: "user", content: "Tell me a story." });
@@ -30,7 +36,7 @@ Each chunk is a JSON object with the following properties:
 }
 ```
 
-We have a couple of utility functions on the stream to help you with the streaming process.
+The stream provides several utility functions for working with streaming responses:
 
 - `stream.finishReason` - The reason the agent stopped streaming.
 - `stream.toolCalls` - The tool calls made by the agent.
@@ -86,7 +92,7 @@ export const weatherInfo = createTool({
 });
 ```
 
-If you want to use the stream in an agent, you can use the `streamVNext` method on the agent and pipe it to the agent's input stream.
+To use streaming within an agent-based tool, call `streamVNext` on the agent and pipe it to the writer:
 
 ```typescript filename="src/mastra/tools/test-tool.ts" showLineNumbers copy
 import { createTool } from "@mastra/core/tools";
@@ -114,5 +120,5 @@ export const weatherInfo = createTool({
 });
 ```
 
-Piping the stream to the agent's input stream will allow us to automatically sum up the usage of the agent so the total usage count can be calculated.
+Piping the stream to the writer enables automatic aggregation of token usage across nested agent calls.
 

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

@@ -69,7 +69,7 @@ Ensure your template meets all requirements outlined in the [Templates Reference
 
 Submit your template using our contribution form:
 
-**[Submit Template Contribution](https://docs.google.com/forms/d/e/1FAIpQLSfiqD4oeOVaqoE3t10KZJw4QM3fxAQPIOcZBqUYkewJIsQKFw/viewform)**
+**[Submit Template Contribution](https://forms.gle/g1CGuwFxqbrb3Rz57)**
 
 ### Required Information
 

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

@@ -5,7 +5,7 @@ description: "Deploy your Mastra applications to Amazon EC2."
 
 import { Callout, Steps, Tabs } from "nextra/components";
 
-## Amazon EC2
+# Amazon EC2
 
 Deploy your Mastra applications to Amazon EC2 (Elastic Cloud Compute).
 
@@ -16,7 +16,7 @@ Deploy your Mastra applications to Amazon EC2 (Elastic Cloud Compute).
   refer to our [getting started guide](/docs/getting-started/installation)
 </Callout>
 
-### Prerequisites
+## Prerequisites
 
 - An AWS account with [EC2](https://aws.amazon.com/ec2/) access
 - An EC2 instance running Ubuntu 24+ or Amazon Linux
@@ -25,11 +25,11 @@ Deploy your Mastra applications to Amazon EC2 (Elastic Cloud Compute).
 - SSL certificate configured (e.g., using [Let's Encrypt](https://letsencrypt.org/))
 - Node.js 18+ installed on your instance
 
-### Deployment Steps
+## Deployment Steps
 
 <Steps>
 
-#### Clone your Mastra application
+### Clone your Mastra application
 
 Connect to your EC2 instance and clone your repository:
 
@@ -57,13 +57,13 @@ Navigate to the repository directory:
 cd "<your-repository>"
 ```
 
-#### Install dependencies
+### Install dependencies
 
 ```bash copy
 npm install
 ```
 
-#### Set up environment variables
+### Set up environment variables
 
 Create a `.env` file and add your environment variables:
 
@@ -78,13 +78,13 @@ OPENAI_API_KEY=<your-openai-api-key>
 # Add other required environment variables
 ```
 
-#### Build the application
+### Build the application
 
 ```bash copy
 npm run build
 ```
 
-#### Run the application
+### Run the application
 
 ```bash copy
 node --import=./.mastra/output/instrumentation.mjs --env-file=".env" .mastra/output/index.mjs
@@ -96,7 +96,7 @@ Your Mastra application will run on port 4111 by default. Ensure your reverse pr
 
 </Steps>
 
-### Connect to your Mastra server
+## Connect to your Mastra server
 
 You can now connect to your Mastra server from your client application using a `MastraClient` from the `@mastra/client-js` package.