@mastra/mcp-docs-server 0.13.26 → 0.13.27-alpha.0

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

@@ -1,5 +1,5 @@
 ---
-title: "Agent Overview | Agent Documentation | Mastra"
+title: "Agent Overview | Agents | Mastra Docs"
 description: Overview of agents in Mastra, detailing their capabilities and how they interact with tools, workflows, and external systems.
 ---
 
@@ -76,9 +76,9 @@ Instructions can be provided in multiple formats for greater flexibility:
 instructions: "You are a helpful assistant."
 
 // System message object
-instructions: { 
-  role: "system", 
-  content: "You are an expert programmer." 
+instructions: {
+  role: "system",
+  content: "You are an expert programmer."
 }
 
 // Array of strings
@@ -112,10 +112,9 @@ Provider-specific options allow you to leverage unique features of different LLM
 
 > See [Agent](../../reference/agents/agent.mdx) for more information.
 
-
 ### Registering an agent
 
-Register your agent in the Mastra instance:
+Register your agent in the Mastra instance to make it available throughout your application. Once registered, it can be called from workflows, tools, or other agents, and has access to shared resources such as memory, logging, and observability features:
 
 ```typescript showLineNumbers filename="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core/mastra";
@@ -145,7 +144,7 @@ Use `.generate()` to get a response from an agent. Pass a single string for simp
 
 ### Generating text
 
-Call `.generate()` with an array of message objects that include `role` and `content`:
+Call `.generate()` with an array of message objects containing `role` and `content`. The `role` defines the speaker for each message. Typical roles are `user` for human input, `assistant` for agent responses, and `system` for instructions. This structure helps the LLM maintain conversation flow and generate contextually appropriate responses.
 
 ```typescript showLineNumbers copy
 const response = await testAgent.generate([
@@ -158,49 +157,9 @@ const response = await testAgent.generate([
 console.log(response.text);
 ```
 
-## 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 text
-
-Use `.stream()` with an array of message objects that include `role` and `content`:
-
-```typescript showLineNumbers copy
-const stream = await testAgent.stream([
-  { 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" }
-]);
-
-for await (const chunk of stream.textStream) {
-  process.stdout.write(chunk);
-}
-```
-
-### Completion using `onFinish()`
-
-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
-const stream = await testAgent.stream("Help me organize my day", {
-  onFinish: ({ steps, text, finishReason, usage }) => {
-    console.log({ steps, text, finishReason, usage });
-  }
-});
-
-for await (const chunk of stream.textStream) {
-  process.stdout.write(chunk);
-}
-```
-
 ## Structured output
 
-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.
+Agents can return structured, type-safe data by defining the expected output using either [Zod](https://zod.dev/) or [JSON Schema](https://json-schema.org/). We recommend Zod for better TypeScript support and developer experience. The parsed result is available on `response.object`, allowing you to work directly with validated and typed data.
 
 ### Using Zod
 
@@ -233,7 +192,7 @@ console.log(response.object);
 
 #### Agents with tools
 
-To generate structured output with agents that use tools, use the `experimental_output` property:
+To generate structured output with agents that use tools, use the `output` property:
 
 ```typescript {6} showLineNumbers copy
 import { z } from "zod";
@@ -241,7 +200,7 @@ import { z } from "zod";
 const response = await testAgent.generate(
   // ...
   {
-    experimental_output: z.object({
+    output: z.object({
       summary: z.string(),
       keywords: z.array(z.string())
     })
@@ -251,7 +210,7 @@ const response = await testAgent.generate(
 console.log(response.object);
 ```
 
-## Describing images
+## Working with images
 
 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.
 
@@ -284,7 +243,7 @@ For a detailed guide to creating and configuring tools, see the [Tools Overview]
 
 ### 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:
+The `maxSteps` parameter controls the maximum number of sequential LLM calls an agent can make. Each step includes generating a response, executing any tool calls, and processing the result. Limiting steps helps prevent infinite loops, reduce latency, and control token usage for agents that use tools. The default is 1, but can be increased:
 
 ```typescript showLineNumbers copy
 const response = await testAgent.generate("Help me organize my day", {

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

@@ -1,63 +1,68 @@
 ---
-title: "Using Tools with Agents | Agents | Mastra Docs"
+title: "Tools and MCP | Agents | Mastra Docs"
 description: Learn how to create tools, add them to Mastra agents, and integrate tools from MCP servers.
 ---
 
-# Using Tools with Agents
+# Tools and MCP
 
-Tools are typed functions that can be executed by agents or workflows. Each tool has a schema defining its inputs, an executor function implementing its logic, and optional access to configured integrations.
+Tools are typed functions that can be executed by agents or workflows to help them carry out specific tasks like sending a message, querying a database, or calling an external API. Each tool defines its expected inputs, contains the logic to perform its operation, and may delegate execution to an MCP client for accessing external systems. They give agents a structured way to move beyond language generation and enable deterministic outcomes through well-defined interfaces.
 
 Mastra supports two patterns for providing tools to agents:
+
 - **Direct assignment**: Static tools available at initialization
-- **Function-based**: Dynamic tools resolved based on runtime context  
+- **Function-based**: Dynamic tools resolved based on runtime context
 
-## Creating Tools
+## Creating a tool
 
-Here's a basic example of creating a tool:
+This example shows how to create a simple tool that asynchronously fetches data from a weather API:
 
-```typescript filename="src/mastra/tools/weatherInfo.ts" copy
+```typescript filename="src/mastra/tools/weather-tool.ts" showLineNumbers copy
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 
-export const weatherInfo = createTool({
-  id: "Get Weather Information",
+export const weatherTool = createTool({
+  id: "weather-tool",
+  description: "Fetches the current weather information for a given city",
   inputSchema: z.object({
     city: z.string(),
   }),
-  description: `Fetches the current weather information for a given city`,
-  execute: async ({ context: { city } }) => {
-    // Tool logic here (e.g., API call)
-    console.log("Using tool to fetch weather information for", city);
-    return { temperature: 20, conditions: "Sunny" }; // Example return
+  execute: async ({ context }) => {
+    const { city } = context;
+    const response = await fetch(`https://weather.service?city=${city}`);
+
+    const { temperature, conditions } = await response.json();
+
+    return { temperature, conditions };
   },
 });
 ```
 
-For details on creating and designing tools, see the [Tools Overview](/docs/tools-mcp/overview).
+For details on creating and designing tools, see the [Tools Overview](../tools-mcp/overview.mdx).
 
-## Adding Tools to an Agent
+## Adding tools to an agent
 
 To make a tool available to an agent, add it to the `tools` property in the agent's configuration.
 
-```typescript filename="src/mastra/agents/weatherAgent.ts" {3,11}
+```typescript {3,12} filename="src/mastra/agents/weather-agent.ts" showLineNumbers copy
 import { Agent } from "@mastra/core/agent";
 import { openai } from "@ai-sdk/openai";
-import { weatherInfo } from "../tools/weatherInfo";
+import { weatherTool } from "../tools/weather-tool";
 
 export const weatherAgent = new Agent({
   name: "Weather Agent",
-  instructions:
-    "You are a helpful assistant that provides current weather information. When asked about the weather, use the weather information tool to fetch the data.",
+  instructions: `
+    You are a helpful assistant that provides weather information.
+    When asked about the weather, use the weatherTool to fetch the data.`,
   model: openai("gpt-4o-mini"),
   tools: {
-    weatherInfo,
+    weatherTool,
   },
 });
 ```
 
 When you call the agent, it can now decide to use the configured tool based on its instructions and the user's prompt.
 
-## Adding MCP Tools to an Agent
+## Adding MCP tools to an agent
 
 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) provides a standardized way for AI models to discover and interact with external tools and resources. You can connect your Mastra agent to MCP servers to use tools provided by third parties.
 
@@ -71,7 +76,7 @@ First, install the Mastra MCP package:
 npm install @mastra/mcp@latest
 ```
 
-### Using MCP Tools
+### Using MCP tools
 
 Because there are so many MCP server registries to choose from, we've created an [MCP Registry Registry](https://mastra.ai/mcp-registry-registry) to help you find MCP servers.
 
@@ -121,7 +126,7 @@ import { openai } from "@ai-sdk/openai";
 
 const myAgent = new Agent({
   name: "My Agent",
-  description: "An agent that can use tools from an http MCP server", 
+  description: "An agent that can use tools from an http MCP server",
   instructions: "You can use remote calculation tools.",
   model: openai("gpt-4o-mini"),
   tools: async () => {
@@ -148,7 +153,7 @@ export const mcpServer = new MCPServer({
 
 For more details on configuring `MCPClient` and the difference between static and dynamic MCP server configurations, see the [MCP Overview](/docs/tools-mcp/mcp-overview).
 
-## Accessing MCP Resources
+## Accessing MCP resources
 
 In addition to tools, MCP servers can also expose resources - data or content that can be retrieved and used in your application.
 
@@ -169,11 +174,11 @@ if (resources.filesystem) {
 
 Each resource has a URI, name, description, and MIME type. The `getResources()` method handles errors gracefully - if a server fails or doesn't support resources, it will be omitted from the results.
 
-## Accessing MCP Prompts
+## Accessing MCP prompts
 
 MCP servers can also expose prompts, which represent structured message templates or conversational context for agents.
 
-### Listing Prompts
+### Listing prompts
 
 ```typescript filename="src/mastra/prompts.ts"
 import { mcp } from "./mcp";
@@ -192,7 +197,7 @@ if (prompts.weather) {
 
 Each prompt has a name, description, and (optional) version.
 
-### Retrieving a Prompt and Its Messages
+### Retrieving a prompt and its messages
 
 ```typescript filename="src/mastra/prompts.ts"
 const { prompt, messages } = await mcp.prompts.get({ serverName: "weather", name: "current" });
@@ -200,7 +205,7 @@ console.log(prompt);    // { name: "current", version: "v1", ... }
 console.log(messages);  // [ { role: "assistant", content: { type: "text", text: "..." } }, ... ]
 ```
 
-## Exposing Agents as Tools via MCPServer
+## Exposing agents as tools via `MCPServer`
 
 In addition to using tools from MCP servers, your Mastra Agents themselves can be exposed as tools to any MCP-compatible client using Mastra's `MCPServer`.
 

package/.docs/raw/deployment/serverless-platforms/vercel-deployer.mdx

@@ -29,6 +29,24 @@ export const mastra = new Mastra({
 
 > See the [VercelDeployer](/reference/deployer/vercel) API reference for all available configuration options.
 
+### Optional overrides
+
+The Vercel deployer can write a few high‑value settings into the Vercel Output API function config (`.vc-config.json`):
+
+- `maxDuration?: number` — Function execution timeout (seconds)
+- `memory?: number` — Function memory allocation (MB)
+- `regions?: string[]` — Regions (e.g. `['sfo1','iad1']`)
+
+Example:
+
+```ts filename="src/mastra/index.ts" showLineNumbers copy
+deployer: new VercelDeployer({
+  maxDuration: 600,
+  memory: 1536,
+  regions: ["sfo1", "iad1"],
+})
+```
+
 ## Continuous integration
 
 After connecting your Mastra project’s Git repository to Vercel, update the project settings. In the Vercel dashboard, go to **Settings** > **Build and Deployment**, and under **Framework settings**, set the following:

package/.docs/raw/frameworks/agentic-uis/ai-sdk.mdx

@@ -384,13 +384,13 @@ This guide covers Mastra-specific considerations when migrating from AI SDK v4 t
 
 > Please add any feedback or bug reports to the [AI SDK v5 mega issue in Github.](https://github.com/mastra-ai/mastra/issues/5470)
 
-### Experimental streamVNext Support
+### Stream Support
 
-Mastra's experimental `streamVNext` method now includes native AI SDK v5 support through the `format` parameter. This provides seamless integration with AI SDK v5's streaming interfaces without requiring compatibility wrappers.
+Mastra's experimental `stream` method now includes native AI SDK v5 support through the `format` parameter. This provides seamless integration with AI SDK v5's streaming interfaces without requiring compatibility wrappers.
 
 ```typescript
-// Use streamVNext with AI SDK v5 format
-const stream = await agent.streamVNext(messages, {
+// Use stream with AI SDK v5 format
+const stream = await agent.stream(messages, {
   format: 'aisdk'  // Enable AI SDK v5 compatibility
 });
 
@@ -483,10 +483,6 @@ const { error, status, sendMessage, messages, regenerate, stop } =
   });
 ```
 
-<Callout type="info">
-  **Note**: The `streamVNext` method with format support is experimental and may change as we refine the feature based on feedback. See the [Agent Streaming documentation](/docs/agents/streaming) for more details about streamVNext.
-</Callout>
-
 ### Type Inference for Tools
 
 When using tools with TypeScript in AI SDK v5, Mastra provides type inference helpers to ensure type safety for your tool inputs and outputs.

package/.docs/raw/getting-started/installation.mdx

@@ -405,10 +405,9 @@ Install the latest version to the `@ai-sdk/openai` package:
   </Tab>
 </Tabs>
 
-Update the `planActivities` step in `src/mastra/workflows/weather-workflow.ts` as follow:
+Update the `planActivities` step in `src/mastra/workflows/weather-workflow.ts` as follows:
 ```ts filename="src/mastra/workflows/weather-workflow.ts" showLineNumbers{150} copy
-const response = await agent.stream([ // [!code --]
-const response = await agent.streamVNext([ // [!code ++]
+const response = await agent.stream([
   {
     role: 'user',
     content: prompt,

package/.docs/raw/getting-started/model-providers.mdx

@@ -7,150 +7,55 @@ import { Callout } from "nextra/components"
 
 # Model Providers
 
-Model providers are used to interact with different language models. Mastra uses [Vercel's AI SDK](https://sdk.vercel.ai) as a model routing layer to provide a similar syntax for many models:
+Mastra's unified model router gives you access to 541+ models from 38 providers with a single API. Switch between models and providers without changing your code. Automatic environment variable detection handles authentication, while TypeScript provides full autocomplete for every model.
 
-```typescript showLineNumbers copy {1,7} filename="src/mastra/agents/weather-agent.ts"
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
+## Quick Start
+
+Simply use the `provider/model` string pattern:
+
+```typescript showLineNumbers copy filename="src/mastra/agents/weather-agent.ts"
+import { Agent } from "@mastra/core";
 
 const agent = new Agent({
   name: "WeatherAgent",
-  instructions: "Instructions for the agent...",
-  model: openai("gpt-4-turbo"),
+  instructions: "You are a helpful weather assistant",
+  model: "openai/gpt-4o"
 });
 
 const result = await agent.generate("What is the weather like?");
 ```
 
-## Types of AI SDK model providers
-
-Model providers from the AI SDK can be grouped into three main categories:
-
-- [Official providers maintained by the AI SDK team](/docs/getting-started/model-providers#official-providers)
-- [OpenAI-compatible providers](/docs/getting-started/model-providers#openai-compatible-providers)
-- [Community providers](/docs/getting-started/model-providers#community-providers)
-
-> You can find a list of all available model providers in the [AI SDK documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
+## Browse Providers
 
 <Callout>
-AI SDK model providers are packages that need to be installed in your Mastra project.
-The default model provider selected during the installation process is installed in the project.
-
-If you want to use a different model provider, you need to install it in your project as well.
+  **[→ View all 38 providers and 7 gateways](../../models)**
 </Callout>
 
-Here are some examples of how Mastra agents can be configured to use the different types of model providers:
-
-### Official providers
-
-Official model providers are maintained by the AI SDK team.
-Their packages are usually prefixed with `@ai-sdk/`, e.g. `@ai-sdk/anthropic`, `@ai-sdk/openai`, etc.
-
-```typescript showLineNumbers copy {1,7} filename="src/mastra/agents/weather-agent.ts"
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-
-const agent = new Agent({
-  name: "WeatherAgent",
-  instructions: "Instructions for the agent...",
-  model: openai("gpt-4-turbo"),
-});
-```
-
-Additional configuration may be done by importing a helper function from the AI SDK provider.
-Here's an example using the OpenAI provider:
-
-```typescript showLineNumbers copy filename="src/mastra/agents/weather-agent.ts" {1,4-8,13}
-import { createOpenAI } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-
-const openai = createOpenAI({
-  baseUrl: "<your-custom-base-url>",
-  apiKey: "<your-custom-api-key>",
-  ...otherOptions,
-});
-
-const agent = new Agent({
-  name: "WeatherAgent",
-  instructions: "Instructions for the agent...",
-  model: openai("<model-name>"),
-});
-```
-
-### OpenAI-compatible providers
+## Configuration
 
-Some language model providers implement the OpenAI API. For these providers, you can use the [`@ai-sdk/openai-compatible`](https://www.npmjs.com/package/@ai-sdk/openai-compatible) provider.
+Models automatically detect API keys from environment variables.
 
-Here's the general setup and provider instance creation:
+## AI SDK Compatibility
 
-```typescript showLineNumbers copy filename="src/mastra/agents/weather-agent.ts" {1,4-14,19}
-import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
-import { Agent } from "@mastra/core/agent";
+While Mastra provides built-in support for 541+ models, you can also use [Vercel AI SDK](https://sdk.vercel.ai/providers/ai-sdk-providers) model providers for additional flexibility:
 
-const openaiCompatible = createOpenAICompatible({
-  name: "<model-name>",
-  baseUrl: "<base-url>",
-  apiKey: "<api-key>",
-  headers: {},
-  queryParams: {},
-  fetch: async (url, options) => {
-    // custom fetch logic
-    return fetch(url, options);
-  },
-});
-
-const agent = new Agent({
-  name: "WeatherAgent",
-  instructions: "Instructions for the agent...",
-  model: openaiCompatible("<model-name>"),
-});
-```
-
-For more information on the OpenAI-compatible provider, please refer to the [AI SDK documentation](https://ai-sdk.dev/providers/openai-compatible-providers).
-
-### Community providers
-
-The AI SDK provides a [Language Model Specification](https://github.com/vercel/ai/tree/main/packages/provider/src/language-model/v1).
-Following this specification, you can create your own model provider compatible with the AI SDK.
-
-Some community providers have implemented this specification and are compatible with the AI SDK.
-We will look at one such provider, the Ollama provider available in the [`ollama-ai-provider-v2`](https://github.com/nordwestt/ollama-ai-provider-v2) package.
-
-Here's an example:
-
-```typescript showLineNumbers copy filename="src/mastra/agents/weather-agent.ts" {1,7}
-import { ollama } from "ollama-ai-provider-v2";
-import { Agent } from "@mastra/core/agent";
-
-const agent = new Agent({
-  name: "WeatherAgent",
-  instructions: "Instructions for the agent...",
-  model: ollama("llama3.2:latest"),
-});
-```
-
-You can also configure the Ollama provider like so:
-
-```typescript showLineNumbers copy filename="src/mastra/agents/weather-agent.ts" {1,4-7,12}
-import { createOllama } from "ollama-ai-provider-v2";
-import { Agent } from "@mastra/core/agent";
-
-const ollama = createOllama({
-  baseUrl: "<your-custom-base-url>",
-  ...otherOptions,
-});
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core";
 
 const agent = new Agent({
-  name: "WeatherAgent",
-  instructions: "Instructions for the agent...",
-  model: ollama("llama3.2:latest"),
+  name: "AISDKAgent",
+  model: openai("gpt-4-turbo")  // AI SDK model provider
 });
 ```
 
-For more information on the Ollama provider and other available community providers, please refer to the [AI SDK documentation](https://ai-sdk.dev/providers/community-providers).
-
-<Callout>
-While this example shows how to use the Ollama provider, other providers like `openrouter`, `azure`, etc. may also be used.
+<Callout type="info">
+**Recommendation**: Use Mastra's built-in model router (`"provider/model"` strings) for simplicity. Use AI SDK providers only when you need specific features not available in the built-in providers.
 </Callout>
 
-Different AI providers may have different options for configuration. Please refer to the [AI SDK documentation](https://ai-sdk.dev/providers/ai-sdk-providers) for more information.
+## Learn More
+
+- [📚 Browse All Model Providers](../../models) - Complete list with examples
+- [🚀 Agent Documentation](/reference/agents/agent) - Using models with agents
+- [⚙️ Environment Variables](/docs/deployment/environment-variables) - Configuration guide
+- [🔧 Tool Configuration](/docs/tools/overview) - Adding tools to agents

package/.docs/raw/memory/semantic-recall.mdx

@@ -170,7 +170,7 @@ const agent = new Agent({
 });
 ```
 
-For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](/reference/rag/pg#index-configuration-guide).
+For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](/reference/vectors/pg#index-configuration-guide).
 
 ### Disabling
 

package/.docs/raw/reference/agents/agent.mdx

@@ -162,7 +162,7 @@ export const agent = new Agent({
       description: "Default options used when calling `stream()`.",
     },
     {
-      name: "defaultVNextStreamOptions",
+      name: "defaultStreamOptions",
       type: "AgentExecutionOptions | ({ runtimeContext: RuntimeContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>",
       isOptional: true,
       description: "Default options used when calling `stream()` in vNext mode.",