@mastra/mcp-docs-server 0.13.27 → 0.13.28-alpha.2

package/.docs/raw/agents/runtime-context.mdx

@@ -1,9 +1,9 @@
 ---
-title: "Runtime context | Agents | Mastra Docs"
+title: "Runtime Context | Agents | Mastra Docs"
 description: Learn how to use Mastra's RuntimeContext to provide dynamic, request-specific configuration to agents.
 ---
 
-# Agent Runtime Context
+# Runtime Context
 
 Mastra provides `RuntimeContext`, a dependency injection system that lets you configure agents with runtime variables. If you find yourself creating multiple agents that perform similar tasks, runtime context allows you to consolidate them into a single, more flexible agent.
 
@@ -46,9 +46,9 @@ export const testWeatherAgent = new Agent({
 
 ### Example tool
 
-This tool exports a `WeatherRuntimeContext` type, which can be used anywhere `RuntimeContext` is used to enable type-safe access to runtime configuration.
+This tool exports a `WeatherRuntimeContext` type, enabling type-safe access to runtime configuration wherever the tool’s `runtimeContext` is used. It extracts `city` from `context`, which is derived from the user message passed to `.generate()`, and uses it to query a weather service API.
 
-```typescript {4-6} filename="src/mastra/tools/test-weather-tool.ts" showLineNumbers copy
+```typescript {4-6, 15} filename="src/mastra/tools/test-weather-tool.ts" showLineNumbers copy
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 
@@ -58,26 +58,21 @@ export type WeatherRuntimeContext = {
 
 export const testWeatherTool = createTool({
   id: "test-weather-tool",
-  description: "Get weather for a location",
+  description: "Fetches the current weather for a given city",
   inputSchema: z.object({
-    location: z.string()
-  }),
-  outputSchema: z.object({
-    metric: z.string(),
-    temperature: z.number(),
-    weather: z.string()
+    city: z.string()
   }),
   execute: async ({ context, runtimeContext }) => {
-    const { location } = context;
+    const { city } = context;
     const unit = runtimeContext.get("temperature-unit") as WeatherRuntimeContext["temperature-unit"];
 
-    const temperature = 30;
-    const weather = "Sunny";
+    const response = await fetch(`https://weather.service?city=${city}`);
+    const { temperature, conditions } = await response.json();
 
     return {
       metric: unit === "celsius" ? "°C" : "°F",
       temperature,
-      weather
+      conditions
     };
   }
 });
@@ -96,7 +91,7 @@ const agent = mastra.getAgent("testWeatherAgent");
 
 const runtimeContext = new RuntimeContext<WeatherRuntimeContext>();
 
-runtimeContext.set("temperature-unit", "fahrenheit");
+runtimeContext.set("temperature-unit", "celsius");
 
 const response = await agent.generate("What's the weather in London?", {
   runtimeContext

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

@@ -22,7 +22,7 @@ import { z } from "zod";
 
 export const weatherTool = createTool({
   id: "weather-tool",
-  description: "Fetches the current weather information for a given city",
+  description: "Fetches the current weather for a given city",
   inputSchema: z.object({
     city: z.string(),
   }),

package/.docs/raw/frameworks/agentic-uis/assistant-ui.mdx

@@ -95,9 +95,16 @@ The default Assistant UI setup configures the chat runtime to use a local API ro
 
 Find the `useChatRuntime` hook in the `assistant-ui` project, typically at `app/assistant.tsx` and change the `api` property to the full URL of your Mastra agent's stream endpoint:
 
-```typescript showLineNumbers copy filename="app/assistant.tsx" {2}
+```typescript showLineNumbers copy filename="app/assistant.tsx" {6}
+import {
+  useChatRuntime,
+  AssistantChatTransport,
+} from "@assistant-ui/react-ai-sdk";
+
 const runtime = useChatRuntime({
-    api: "http://localhost:4111/api/agents/weatherAgent/stream",
+  transport: new AssistantChatTransport({
+    api: "MASTRA_ENDPOINT",
+  }),
 });
 ```
 

package/.docs/raw/getting-started/mcp-docs-server.mdx

@@ -4,167 +4,55 @@ description: "Learn how to use the Mastra MCP documentation server in your IDE t
 ---
 
 import YouTube from "@/components/youtube";
-import { Tabs } from "nextra/components";
 
 # Mastra Docs Server
 
-The `@mastra/mcp-docs-server` package provides direct access to Mastra’s full knowledge base, including documentation, code examples, blog posts, and changelogs, via the MCP protocol. It works with Cursor, Windsurf, Cline, Claude Code, or any tool that supports MCP.
+The `@mastra/mcp-docs-server` package provides direct access to Mastra’s full knowledge base, including documentation, code examples, blog posts, and changelogs, via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It works with Cursor, Windsurf, Cline, Claude Code, or any tool that supports MCP.
 
-<YouTube id="vciV57lF0og" />
-
-These tools are designed to help agents retrieve precise, task-specific information—whether you're adding a feature to an agent, scaffolding a new project, or exploring how something works.
-
-## How it works
-
-Once installed you can write prompts and assume the agent will understand everything about Mastra.
-
-### Add features
-
-- "Add evals to my agent and write tests"
-- "Write me a workflow that does the following `[task]`"
-- "Make a new tool that allows my agent to access `[3rd party API]`"
-
-### Ask about integrations
-
-- "Does Mastra work with the AI SDK?
-  How can I use it in my `[React/Svelte/etc]` project?"
-- "What's the latest Mastra news around MCP?"
-- "Does Mastra support `[provider]` speech and voice APIs? Show me an example in my code of how I can use it."
-
-### Debug or update existing code
-
-- "I'm running into a bug with agent memory, have there been any related changes or bug fixes recently?"
-- "How does working memory behave in Mastra and how can I use it to do `[task]`? It doesn't seem to work the way I expect."
-- "I saw there are new workflow features, explain them to me and then update `[workflow]` to use them."
-
-**And more** - if you have a question, try asking your IDE and let it look it up for you.
+These tools are designed to help agents retrieve precise, task-specific information — whether you're adding a feature to an agent, scaffolding a new project, or exploring how something works.
 
-## Automatic installation
+In this guide you'll learn how to add Mastra's MCP server to your AI tooling.
 
-For **new** projects, the MCP Docs Server can be added during installation either through the [interactive](/docs/getting-started/installation#interactive) setup prompts, or by specifying the `-m` flag using the [non-interactive](/docs/getting-started/installation#non-interactive) command.
+<YouTube id="vciV57lF0og" />
 
-## Manual installation
+## Installation
 
-To add the MCP Docs Server to an existing project, install it manually.
+### create-mastra
 
-- **Cursor**: Edit `.cursor/mcp.json` in your project root, or `~/.cursor/mcp.json` for global configuration
-- **Windsurf**: Edit `~/.codeium/windsurf/mcp_config.json` (only supports global configuration)
-- **VSCode**: Either move the created `.vscode` folder into the top-level of your workspace or open the created folder as your new workspace root. Edit `~/.vscode/mcp.json` in your project root. Add the following configuration:
-- **Claude Code**: Run the `claude mcp add` command as shown below.
+During the interactive [create-mastra](/reference/cli/create-mastra) wizard, choose one of your tools in the MCP step.
 
-### MacOS/Linux
+### Manual setup
 
-{/*
-LLM CONTEXT: This Tabs component shows MCP server configuration for different IDEs on MacOS/Linux.
-Each tab displays the JSON configuration needed to set up the Mastra MCP docs server in that specific IDE.
-The tabs help users find the correct configuration format for their IDE (Cursor, Windsurf, or VSCode).
-Each tab shows the exact JSON structure and file paths needed for that IDE's MCP configuration.
-*/}
+If there are no specific instructions for your tool below, you may be able to add the MCP server with this common JSON configuration anyways.
 
-<Tabs items={["Cursor", "Windsurf", "VSCode", "Claude Code"]}>
-  <Tabs.Tab>
-```json
-{
-  "mcpServers": {
-    "mastra": {
-      "command": "npx",
-      "args": ["-y", "@mastra/mcp-docs-server"]
-    }
-  }
-}
-```
-  </Tabs.Tab>
-  <Tabs.Tab>
-```json
-{
-  "mcpServers": {
-    "mastra": {
-      "command": "npx",
-      "args": ["-y", "@mastra/mcp-docs-server"]
-    }
-  }
-}
-```
-  </Tabs.Tab>
-  <Tabs.Tab>
-```json
-{
-  "servers": {
-    "mastra": {
-      "command": "npx",
-      "args": ["-y", "@mastra/mcp-docs-server"],
-      "type": "stdio"
-    }
-  }
-}
-```
-  </Tabs.Tab>
-  <Tabs.Tab>
-```bash
-claude mcp add mastra -- npx -y @mastra/mcp-docs-server
-```
-  </Tabs.Tab>
-</Tabs>
-
-### Windows
-
-{/*
-LLM CONTEXT: This Tabs component shows MCP server configuration for different IDEs on Windows.
-Each tab displays the Windows-specific JSON configuration needed to set up the Mastra MCP docs server.
-The tabs help Windows users find the correct configuration format for their IDE, using cmd instead of direct npx.
-Each tab shows the Windows-specific command structure needed for that IDE's MCP configuration.
-On latest Windsurf and Cursor the direct npx command works, while it's still unconfirmed if this has been fixed for VSCode.
-*/}
-
-<Tabs items={["Cursor", "Windsurf", "VSCode", "Claude Code"]}>
-  <Tabs.Tab>
-```json
-{
-  "mcpServers": {
-    "mastra": {
-      "command": "npx",
-      "args": ["-y", "@mastra/mcp-docs-server"]
-    }
-  }
-}
-```
-  </Tabs.Tab>
-  <Tabs.Tab>
-```json
+```json copy
 {
   "mcpServers": {
     "mastra": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "@mastra/mcp-docs-server"]
     }
   }
 }
 ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-```json
-{
-  "servers": {
-    "mastra": {
-      "command": "cmd",
-      "args": ["/c", "npx", "-y", "@mastra/mcp-docs-server"],
-      "type": "stdio"
-    }
-  }
-}
-```
-  </Tabs.Tab>
-  <Tabs.Tab>
-```bash
+
+### Claude Code CLI
+
+Install using the terminal command:
+
+```bash copy
 claude mcp add mastra -- npx -y @mastra/mcp-docs-server
 ```
-  </Tabs.Tab>
-</Tabs>
 
-## After configuration
+[More info on using MCP servers with Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)
 
 ### Cursor
 
+Install by clicking the button below:
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=mastra&config=eyJjb21tYW5kIjoibnB4IC15IEBtYXN0cmEvbWNwLWRvY3Mtc2VydmVyIn0%3D)
+
 If you followed the automatic installation, you'll see a popup when you open cursor in the bottom left corner to prompt you to enable the Mastra Docs MCP Server.
 
 <img
@@ -173,32 +61,40 @@ If you followed the automatic installation, you'll see a popup when you open cur
   width={800}
 />
 
-Otherwise, for manual installation, do the following.
-
-1. Open Cursor settings.
-2. Navigate to MCP settings.
-3. Click "enable" on the Mastra MCP server.
-4. If you have an agent chat open, you'll need to re-open it or start a new chat to use the MCP server.
-
-### Windsurf
-
-1. Fully quit and re-open Windsurf.
-2. If tool calls start failing, go to Windsurfs MCP settings and re-start the MCP server. This is a common Windsurf MCP issue and isn't related to Mastra. Right now Cursor's MCP implementation is more stable than Windsurfs is.
-
-In both IDEs it may take a minute for the MCP server to start the first time as it needs to download the package from npm.
+[More info on using MCP servers with Cursor](https://cursor.com/de/docs/context/mcp)
+
+### Visual Studio Code
+
+1. Create a `.vscode/mcp.json` file in your workspace
+2. Insert the following configuration:
+
+    ```json copy
+    {
+      "servers": {
+        "mastra": {
+          "type": "stdio",
+          "command": "npx",
+          "args": [
+            "-y",
+            "@mastra/mcp-docs-server"
+          ]
+        }
+      }
+    }
+    ```
 
-### VSCode
+Once you installed the MCP server, you can use it like so:
 
 1. Open VSCode settings.
 2. Navigate to MCP settings.
 3. Click "enable" on the Chat > MCP option.
 
-<img
-  src="/image/vscode-mcp-setting.png"
-  alt="Settings page of VSCode to enable MCP"
-  width={800}
-  className="rounded-lg"
-/>
+    <img
+      src="/image/vscode-mcp-setting.png"
+      alt="Settings page of VSCode to enable MCP"
+      width={800}
+      className="rounded-lg"
+    />
 
 MCP only works in Agent mode in VSCode. Once you are in agent mode, open the `mcp.json` file and click the "start" button. Note that the "start" button will only appear if the `.vscode` folder containing `mcp.json` is in your workspace root, or the highest level of the in-editor file explorer.
 
@@ -209,7 +105,7 @@ MCP only works in Agent mode in VSCode. Once you are in agent mode, open the `mc
   className="rounded-lg"
 />
 
-After starting the mcp server, click the tools button in the copilot pane to see available tools.
+After starting the MCP server, click the tools button in the Copilot pane to see available tools.
 
 <img
   src="/image/vscode-mcp-running.png"
@@ -218,48 +114,57 @@ After starting the mcp server, click the tools button in the copilot pane to see
   className="rounded-lg"
 />
 
-## Available agent tools
-
-### Documentation
+[More info on using MCP servers with Visual Studio Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
 
-Access Mastra's complete documentation:
+### Windsurf
 
-- Getting started / installation.
-- Guides and tutorials.
-- API references.
+1. Open `~/.codeium/windsurf/mcp_config.json` in your editor
+2. Insert the following configuration:
+
+    ```json copy
+    {
+      "mcpServers": {
+        "mastra": {
+          "command": "npx",
+          "args": ["-y", "@mastra/mcp-docs-server"]
+        }
+      }
+    }
+    ```
+3. Save the configuration and restart Windsurf
 
-### Examples
+[More info on using MCP servers with Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json)
 
-Browse code examples:
+## Usage
 
-- Complete project structures.
-- Implementation patterns.
-- Best practices.
+Once configured, you can ask your AI tool questions about Mastra or instruct it to take actions. For these steps, it'll take the up-to-date information from Mastra's MCP server.
 
-### Blog posts
+**Add features:**
 
-Search the blog for:
+- "Add evals to my agent and write tests"
+- "Write me a workflow that does the following `[task]`"
+- "Make a new tool that allows my agent to access `[3rd party API]`"
 
-- Technical posts.
-- Changelog and feature announcements.
-- AI news and updates.
+**Ask about integrations:**
 
-### Package changes
+- "Does Mastra work with the AI SDK?
+  How can I use it in my `[React/Svelte/etc]` project?"
+- "What's the latest Mastra news around MCP?"
+- "Does Mastra support `[provider]` speech and voice APIs? Show me an example in my code of how I can use it."
 
-Track updates for Mastra and `@mastra/*` packages:
+**Debug or update existing code:**
 
-- Bug fixes.
-- New features.
-- Breaking changes.
+- "I'm running into a bug with agent memory, have there been any related changes or bug fixes recently?"
+- "How does working memory behave in Mastra and how can I use it to do `[task]`? It doesn't seem to work the way I expect."
+- "I saw there are new workflow features, explain them to me and then update `[workflow]` to use them."
 
-## Common issues
+### Troubleshooting
 
 1. **Server Not Starting**
 
    - Ensure [npx](https://docs.npmjs.com/cli/v11/commands/npx) is installed and working.
    - Check for conflicting MCP servers.
    - Verify your configuration file syntax.
-   - On Windows, make sure to use the Windows-specific configuration.
 
 2. **Tool Calls Failing**
    - Restart the MCP server and/or your IDE.

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

@@ -29,6 +29,8 @@ const result = await agent.generate("What is the weather like?");
 
 <Callout>
   **[→ View all 38 providers and 7 gateways](../../models)**
+
+  Explore our complete catalog with logos, model counts, and documentation for each provider.
 </Callout>
 
 ## Configuration
@@ -56,6 +58,6 @@ const agent = new Agent({
 ## 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
+- [🚀 Agent Documentation](../../reference/agents/agent.mdx) - Using models with agents
+- [⚙️ Environment Variables](../getting-started/installation.mdx#add-your-api-key) - Configuration guide
+- [🔧 Tool Configuration](../agents/using-tools-and-mcp.mdx#adding-tools-to-an-agent) - Adding tools to agents

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

@@ -278,7 +278,7 @@ await agent.network(`
     },
     {
       name: "result",
-      type: "Promise<WorkflowResult<TOutput, TSteps>>",
+      type: "Promise<WorkflowResult<TState, TOutput, TSteps>>",
       description: "A promise that resolves to the final workflow result",
     },
     {

package/.docs/raw/reference/cli/create-mastra.mdx

@@ -1,19 +1,75 @@
 ---
-title: "create-mastra | Create Project | Mastra CLI"
+title: "Reference: create-mastra | CLI"
 description: Documentation for the create-mastra command, which creates a new Mastra project with interactive setup options.
 ---
 
+import { Tabs, Tab } from "@/components/tabs";
+
 # create-mastra
 
-The `create-mastra` command **creates** a new standalone Mastra project. Use this command to scaffold a complete Mastra setup in a dedicated directory.
+The `create-mastra` command **creates** a new standalone Mastra project. Use this command to scaffold a complete Mastra setup in a dedicated directory. You can run it with additional flags to customize the setup process.
 
 ## Usage
 
+<Tabs items={["npm", "yarn", "pnpm", "bun"]}>
+  <Tab>
+    ```bash copy
+    npx create-mastra@latest
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    yarn dlx create-mastra@latest
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    pnpm create mastra@latest
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    bun create mastra@latest
+    ```
+  </Tab>
+</Tabs>
+
+`create-mastra` automatically runs in _interactive_ mode, but you can also specify your project name and template with command line arguments.
+
+<Tabs items={["npm", "yarn", "pnpm", "bun"]}>
+  <Tab>
+    ```bash copy
+    npx create-mastra@latest my-mastra-project -- --template coding-agent
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    yarn dlx create-mastra@latest --template coding-agent
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    pnpm create mastra@latest --template coding-agent
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    bun create mastra@latest --template coding-agent
+    ```
+  </Tab>
+</Tabs>
+
+Check out the [full list](https://mastra.ai/api/templates.json) of templates and use the `slug` as input to the `--template` CLI flag.
+
+You can also use any GitHub repo as a template (it has to be a valid Mastra project):
+
 ```bash
-create-mastra [options]
+npx create-mastra@latest my-mastra-project -- --template mastra-ai/template-coding-agent
 ```
 
-## Options
+## CLI flags
+
+Instead of an interactive prompt you can also define these CLI flags.
 
 <PropertiesTable
   content={[
@@ -33,7 +89,7 @@ create-mastra [options]
     {
       name: "--default",
       type: "boolean",
-      description: "Quick start with defaults(src, OpenAI, no examples)",
+      description: "Quick start with defaults (src, OpenAI, no examples)",
       isOptional: true,
     },
     {