@mastra/mcp-docs-server 1.2.1-alpha.2 → 1.2.1-alpha.4

package/.docs/docs/getting-started/build-with-ai.md

@@ -2,9 +2,13 @@
 
 AI agents may not have up-to-date knowledge about Mastra's APIs, patterns, and best practices. These resources give your AI tools direct access to current Mastra documentation, enabling them to generate accurate code and help you build faster.
 
+To give your agent access to Mastra's documentation, we recommend using **skills**. While the MCP docs server also provides this information, skills will perform better. Use the MCP docs server when you need its tools, e.g. the migration tool.
+
 ## Mastra skills
 
-Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. [Mastra Skills](https://mastra.ai/docs/build-with-ai/skills) contain setup instructions, best practices, and instructions on how to fetch up-to-date information from Mastra's documentation.
+Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. Mastra skills contain setup instructions, best practices, CLI commands, and instructions on how to fetch up-to-date information from Mastra's documentation.
+
+To install all available Mastra skills, run the following command:
 
 **npm**:
 
@@ -30,15 +34,37 @@ yarn dlx skills add mastra-ai/skills
 bun x skills add mastra-ai/skills
 ```
 
-Read the dedicated [Mastra Skills](https://mastra.ai/docs/build-with-ai/skills) guide to learn more about installation options and available skills.
+Mastra skills work with any coding agent that supports the [Skills standard](https://agentskills.io/), including Claude Code, Cursor, Codex, OpenCode, and others.
 
-> **Tip:** If you're interested in giving your agent access to Mastra's documentation, we recommend using **Skills**. While the MCP Docs Server also provides this information, Skills will perform better. Use the MCP Docs Server when you need its tools, e.g. the migration tool.
+They're also available on [GitHub](https://github.com/mastra-ai/skills).
 
-## MCP docs server
+### Update skill
+
+To update to the latest version of the Mastra skill, run:
+
+**npm**:
+
+```bash
+npx skills update mastra
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx skills update mastra
+```
 
-In addition to documentation access, the [MCP Docs Server](https://mastra.ai/docs/build-with-ai/mcp-docs-server) also provides tools to help you migrate to newer versions of Mastra or follow the [Mastra 101 course](https://mastra.ai/course).
+**Yarn**:
+
+```bash
+yarn dlx skills update mastra
+```
 
-Learn how to use the [MCP Docs Server](https://mastra.ai/docs/build-with-ai/mcp-docs-server).
+**Bun**:
+
+```bash
+bun x skills update mastra
+```
 
 ## Mastra CLI
 
@@ -75,7 +101,7 @@ mastra api --url http://localhost:4111 agent run weather-agent '{"messages":"Wha
 mastra api --url http://localhost:4111 trace list
 ```
 
-See the [CLI commands reference](https://mastra.ai/reference/cli/mastra) for the full list of available commands.
+Install the [Mastra skills](#mastra-skills) to teach your agent how to use the CLI. See the [CLI commands reference](https://mastra.ai/reference/cli/mastra) for the full list of available commands.
 
 ## Embedded package docs
 
@@ -102,4 +128,243 @@ Examples for the [introduction page](https://mastra.ai/docs):
 
 ## Mastra's documentation
 
-In addition to the [context files](#context-files) each documentation page also features a "Copy markdown" button at the top of the page. It'll copy the streamlined markdown version to your clipboard. Beside it, you'll find a dropdown menu to open the page on GitHub, in ChatGPT, Claude, and others.
+In addition to the [context files](#context-files) each documentation page also features a "Copy markdown" button at the top of the page. It'll copy the streamlined markdown version to your clipboard. Beside it, you'll find a dropdown menu to open the page on GitHub, in ChatGPT, Claude, and others.
+
+## MCP docs server
+
+The `@mastra/mcp-docs-server` package provides direct access to Mastra’s full documentation via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It works with Cursor, Windsurf, Cline, Claude Code, VS Code, Codex or any tool that supports MCP.
+
+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.
+
+In this guide you'll learn how to add Mastra's MCP server to your AI tooling.
+
+[YouTube video player](https://www.youtube-nocookie.com/embed/vciV57lF0og)
+
+### Installation
+
+#### create-mastra
+
+During the interactive [create-mastra](https://mastra.ai/reference/cli/create-mastra) wizard, choose one of your tools in the MCP step.
+
+#### Manual setup
+
+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.
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+#### Claude Code CLI
+
+Install using the terminal command:
+
+```bash
+claude mcp add --scope project mastra -- npx -y @mastra/mcp-docs-server@latest
+```
+
+This creates a project-scoped `.mcp.json` file if one doesn't already exist. You can use the same command when using Claude Code as a [Visual Studio Code extension](https://code.claude.com/docs/en/vs-code#connect-to-external-tools-with-mcp).
+
+[More info on using MCP servers with Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)
+
+#### OpenAI Codex CLI
+
+1. Register it from the terminal:
+
+   ```bash
+   codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@latest
+   ```
+
+2. Run `codex mcp list` to confirm the server shows as `enabled`.
+
+[More info on using MCP servers with OpenAI Codex](https://developers.openai.com/codex/mcp)
+
+#### Cursor
+
+Install by selecting 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.
+
+![Popup inside Cursor showing: \"New MCP server detected: mastra\". The user can \"Skip\" or \"Enable\" it as an action.](/assets/images/enable-mastra-docs-cursor-cd5872abdc36c0e10951a59a47f25e12.png)
+
+[More info on using MCP servers with Cursor](https://cursor.com/de/docs/context/mcp)
+
+#### Antigravity
+
+Google Antigravity is an agent-first development platform that supports MCP servers for accessing external documentation, APIs, and project context.
+
+1. Open your Antigravity MCP configuration file:
+
+   - Click on **Agent session** and select the **“…” dropdown** at the top of the editor’s side panel, then select **MCP Servers** to access the **MCP Store**.
+   - You can access it through the MCP Store interface in Antigravity
+
+   ![The Antigravity MCP store. At the top is a search bar and below a list of available MCP servers. On the very top right is a dropdown menu.](/assets/images/antigravity_mcp_server-689ea495d9c7139cc431f1f1b9827f9b.png)
+
+2. To add a custom MCP server, select **Manage MCP Servers** at the top of the MCP Store and select **View raw config** in the main tab.
+
+   ![The Antigravity MCP store showing the Manage MCP Servers option and the View raw config button.](/assets/images/antigravity_managed_mcp-b661e8c04b3219000f8d842e5eb26a1a.png)
+
+3. Add the Mastra MCP server configuration:
+
+   ```json
+   {
+     "mcpServers": {
+       "mastra-docs": {
+         "command": "npx",
+         "args": ["-y", "@mastra/mcp-docs-server"]
+       }
+     }
+   }
+   ```
+
+4. Save the configuration and restart Antigravity
+
+   ![The UI shows that the MCP server is enabled. You can also toggle individual tools.](/assets/images/antigravity_final_interface_mcp-7fa132dbe76cdee9f61136a26d6e6615.png)
+
+Once configured, the Mastra MCP server exposes the following to Antigravity agents:
+
+- Indexed documentation and API schemas for Mastra, enabling programmatic retrieval of relevant context during code generation
+- Access to example code snippets and usage patterns stored in Mastra Docs
+- Structured data for error handling and debugging references in the editor
+- Metadata about current Mastra project patterns for code suggestion and completion
+
+The MCP server will appear in Antigravity's MCP Store, where you can manage its connection status and authentication if needed.
+
+[More info on using MCP servers with Antigravity](https://antigravity.google)
+
+#### Visual Studio Code
+
+1. Create a `.vscode/mcp.json` file in your workspace
+
+2. Insert the following configuration:
+
+   ```json
+   {
+     "servers": {
+       "mastra": {
+         "type": "stdio",
+         "command": "npx",
+         "args": ["-y", "@mastra/mcp-docs-server@latest"]
+       }
+     }
+   }
+   ```
+
+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.
+
+   ![Entry in VSCode\'s settings page. The option is called \"Chat \> MCP: Enabled (Preview)\". The description says: \"Enables integration with Model Context Protocol servers to provide additional tools and functionality.\"](/assets/images/vscode-mcp-setting-8d1eb4f3df1e33606503f8c5e937e9e3.png)
+
+MCP only works in Agent mode in VSCode. Once you are in agent mode, open the `mcp.json` file and select 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.
+
+![A screenshot of the mcp.json file showing the start button in the editor](/assets/images/vscode-start-mcp-26480d86080c4907cb497a325de106a4.png)
+
+After starting the MCP server, select the tools button in the Copilot pane to see available tools.
+
+![Tools page of VSCode to see available tools](/assets/images/vscode-mcp-running-d92d6ed234d1148093dc804b0ead3515.png)
+
+[More info on using MCP servers with Visual Studio Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
+
+#### Windsurf
+
+1. Open `~/.codeium/windsurf/mcp_config.json` in your editor
+
+2. Insert the following configuration:
+
+   ```json
+   {
+     "mcpServers": {
+       "mastra": {
+         "command": "npx",
+         "args": ["-y", "@mastra/mcp-docs-server@latest"]
+       }
+     }
+   }
+   ```
+
+3. Save the configuration and restart Windsurf
+
+[More info on using MCP servers with Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json)
+
+#### OpenCode
+
+You can define MCP servers in your [OpenCode configuration](https://opencode.ai/docs/config/) under `mcp`. Create an `opencode.jsonc` file in your project root with the following content:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "mastra": {
+      "type": "local",
+      "command": ["npx", "-y", "@mastra/mcp-docs-server@latest"],
+      "enabled": true
+    }
+  }
+}
+```
+
+[More info on using MCP servers with OpenCode](https://opencode.ai/docs/mcp-servers)
+
+#### Zed
+
+1. Open `~/.config/zed/settings.json` in your editor
+2. Insert the following configuration:
+
+```json
+{
+  "context_servers": {
+    "Mastra": {
+      "command": "npx",
+      "args": ["-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+### Usage
+
+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.
+
+**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?"
+- "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."
+
+#### 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.
+
+2. **Tool Calls Failing**
+
+   - Restart the MCP server and/or your IDE.
+   - Update to the latest version of your IDE.

package/.docs/docs/server/pubsub.md

@@ -10,7 +10,7 @@ Several built-in systems publish and subscribe to events through the same pub/su
 
 - **Workflow execution**: The scheduler publishes a `workflow.start` event, and a long-lived worker consumes it to run the workflow. Step and lifecycle events flow over pub/sub during execution.
 - **Scheduled workflows**: The scheduler dispatches due runs by publishing to the workflow topic. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).
-- **Background tasks**: A task manager dispatches work to a worker group and fans task lifecycle updates out to subscribers, which is how background task streams stay live. See [Background task streaming](https://mastra.ai/docs/streaming/background-task-streaming).
+- **Background tasks**: A task manager dispatches work to a worker group and fans task lifecycle updates out to subscribers, which is how background task streams stay live. See [Background task streaming](https://mastra.ai/docs/agents/background-tasks).
 - **Agent signals**: Sending a signal to an active agent run publishes an event on a thread topic, so a run executing in another process receives the signal.
 - **Resumable streams**: Stream chunks are published per run, so a client that reconnects can replay what it missed.
 
@@ -120,5 +120,5 @@ export const mastra = new Mastra({
 
 - [PubSub reference](https://mastra.ai/reference/pubsub/base)
 - [Mastra class](https://mastra.ai/reference/core/mastra-class)
-- [Background task streaming](https://mastra.ai/docs/streaming/background-task-streaming)
+- [Background task streaming](https://mastra.ai/docs/agents/background-tasks)
 - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows)

package/.docs/docs/workflows/overview.md

@@ -405,6 +405,77 @@ Here's an example of a successful workflow result, showing the `input`, `steps`,
 }
 ```
 
+## Streaming
+
+For generic `writer` API usage, see [Streaming](https://mastra.ai/guides/concepts/streaming).
+
+### Inspecting workflow stream payloads
+
+Events written to the stream are included in the emitted chunks. These chunks can be inspected to access any custom fields, such as event types, intermediate values, or step-specific data.
+
+```typescript
+const testWorkflow = mastra.getWorkflow('testWorkflow')
+
+const run = await testWorkflow.createRun()
+
+const stream = await run.stream({
+  inputData: {
+    value: 'initial data',
+  },
+})
+
+for await (const chunk of stream) {
+  console.log(chunk)
+}
+
+if (result!.status === 'suspended') {
+  // if the workflow is suspended, we can resume it with the resumeStream method
+  const resumedStream = await run.resumeStream({
+    resumeData: { value: 'resume data' },
+  })
+
+  for await (const chunk of resumedStream) {
+    console.log(chunk)
+  }
+}
+```
+
+### Resuming an interrupted workflow stream
+
+If a workflow stream is closed or interrupted for any reason, you can resume it with the `resumeStream` method. This will return a new `ReadableStream` that you can use to observe the workflow events.
+
+```typescript
+const newStream = await run.resumeStream()
+
+for await (const chunk of newStream) {
+  console.log(chunk)
+}
+```
+
+### Workflow using an agent
+
+Pipe an agent's `textStream` to the workflow step's `writer`. This streams partial output, and Mastra automatically aggregates the agent's usage into the workflow run.
+
+```typescript
+import { createStep } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+export const testStep = createStep({
+  execute: async ({ inputData, mastra, writer }) => {
+    const { city } = inputData
+
+    const testAgent = mastra?.getAgent('testAgent')
+    const stream = await testAgent?.stream(`What is the weather in ${city}?`)
+
+    await stream!.textStream.pipeTo(writer!)
+
+    return {
+      value: await stream!.text,
+    }
+  },
+})
+```
+
 ## Restarting active workflow runs
 
 When a workflow run loses connection to the server, it can be restarted from the last active step. This is useful for long-running workflows that might still be running when the server loses connection. Restarting a workflow run will resume execution from the last active step, and the workflow will continue from there.

package/.docs/guides/build-your-ui/ai-sdk-ui.md

@@ -103,7 +103,7 @@ You can also use dynamic workflow routing, see the [`workflowRoute()` reference
 
 > **Agent streaming in workflows:** When a workflow step pipes an agent's stream to the workflow writer (e.g., `await response.fullStream.pipeTo(writer)`), the agent's text chunks and tool calls are forwarded to the UI stream in real time, even when the agent runs inside workflow steps.
 >
-> See [Workflow Streaming](https://mastra.ai/docs/streaming/workflow-streaming) for more details.
+> See [Workflow Streaming](https://mastra.ai/docs/workflows/overview) for more details.
 
 **networkRoute()**:
 
@@ -676,7 +676,7 @@ export function WorkflowChat() {
 }
 ```
 
-For more details on workflow streaming, see [Workflow Streaming](https://mastra.ai/docs/streaming/workflow-streaming).
+For more details on workflow streaming, see [Workflow Streaming](https://mastra.ai/docs/workflows/overview).
 
 ### Rendering network data
 
@@ -906,7 +906,7 @@ export function TaskChat() {
 
 ### Tool streaming
 
-Tools can also stream data using `context.writer.write()` for lower-level control, or pipe an agent's stream directly to the tool's writer. For more details, see [Tool Streaming](https://mastra.ai/docs/streaming/tool-streaming).
+Tools can also stream data using `context.writer.write()` for lower-level control, or pipe an agent's stream directly to the tool's writer. For more details, see [Tool Streaming](https://mastra.ai/docs/agents/using-tools).
 
 ### Examples