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

package/.docs/raw/guides/migrations/upgrade-to-v1/workflows.mdx

@@ -25,7 +25,7 @@ To migrate, replace all calls to `mastra.getWorkflows()` with `mastra.listWorkfl
 You can use Mastra's codemod CLI to update your imports automatically:
 
 ```shell
-npx @mastra/codemod v1/workflows-get-workflows .
+npx @mastra/codemod@beta v1/mastra-plural-apis .
 ```
 
 :::
@@ -52,7 +52,7 @@ To migrate, update references from `runtimeContext` to `requestContext` in step
 You can use Mastra's codemod CLI to update your imports automatically:
 
 ```shell
-npx @mastra/codemod v1/runtime-context .
+npx @mastra/codemod@beta v1/runtime-context .
 ```
 
 :::
@@ -68,6 +68,16 @@ To migrate, rename method calls from `createRunAsync` to `createRun`.
 + await workflow.createRun({ input: { ... } });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/workflow-create-run-async .
+```
+
+:::
+
 ### `runCount` to `retryCount` (deprecated)
 
 The `runCount` parameter has been deprecated in favor of `retryCount` in workflow step execution. This change provides clearer naming that better describes retry behavior. The old `runCount` still works but shows deprecation warnings.
@@ -83,6 +93,16 @@ To migrate, rename `runCount` to `retryCount` in step execution functions.
   });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/workflow-run-count .
+```
+
+:::
+
 ### `getWorkflowRuns` to `listWorkflowRuns`
 
 The `getWorkflowRuns()` method has been renamed to `listWorkflowRuns()`. This change aligns with the convention that `list*` methods return collections.
@@ -94,8 +114,161 @@ To migrate, rename method calls from `getWorkflowRuns` to `listWorkflowRuns`.
 + const runs = await workflow.listWorkflowRuns({ fromDate, toDate });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/workflow-list-runs .
+```
+
+:::
+
+### Inputs are validated by default
+
+Previously, inputs weren't validated by default. The [`validateInputs`](/reference/v1/workflows/workflow#workflowoptions) flag determines whether to validate the workflow inputs or not. This boolean has been flipped to `true`. If you want the old behavior or have workflows whose schemas don't need to be validated, set `validateInputs: false`.
+
+```diff
+createWorkflow({
++  options: {
++    validateInputs: false
++  }
+})
+```
+
+### Step `suspendPayload` validation
+
+Step `suspendPayload` is now validated for steps that have a `suspendSchema` defined. This also uses the `validateInputs` flag to determine whether to validate the `suspendPayload` or not.
+
+```diff
+  createStep({
+    id: "suspend-resume-step",
+    // ... other step properties
+    suspendSchema: z.object({
+      reason: z.string(),
+      otherReason: z.string()
+    }),
+    execute: async ({ suspend, resumeData}) => {
+      if (!resumeData) {
+-       return suspend({ reason: "Suspension reason" }); // Missing otherReason
++       return suspend({ reason: "Suspension reason", otherReason: "Other reason" });
+      }
+      //... continue execution logic
+    },
+  });
+```
+
+### Branch result fields are now optional
+
+The `.branch()` method now returns a schema where all branch output fields are optional. This reflects the runtime behavior where each branch only executes if its condition is truthy, so outputs from any branch may be undefined.
+
+To migrate, update any code that consumes branch outputs to handle optional values.
+
+```diff
+  const workflow = createWorkflow({...})
+    .branch([
+      [condition1, stepA],  // outputSchema: { result: z.string() }
+      [condition2, stepB],  // outputSchema: { data: z.number() }
+    ])
+-   // Previously: stepA.result typed as string, stepB.data typed as number
++   // Now: stepA.result typed as string | undefined, stepB.data typed as number | undefined
+    .then(nextStep);
+```
+
+If your code depends on non-optional types, add runtime checks or provide default values when accessing branch outputs.
+
+### `writableStream` to `outputWriter` in `Run.start()` & `Run.timeTravel()`
+
+The `writableStream` parameter in `Run.start()` and `Run.timeTravel()` has been replaced with `outputWriter`. Instead of passing a `WritableStream`, you now pass an async callback function that receives each workflow event chunk directly.
+
+This change simplifies the API - rather than creating a `WritableStream` wrapper, you handle chunks directly in the callback.
+
+**Example:** Streaming workflow events to an HTTP response (SSE):
+
+```diff
+  const run = await workflow.createRun();
+
+- const stream = new WritableStream({
+-   write(chunk) {
+-     response.write(`data: ${JSON.stringify(chunk)}\n\n`);
+-   }
+- });
+- await run.start({ inputData, writableStream: stream });
+
++ await run.start({
++   inputData,
++   outputWriter: async (chunk) => {
++     response.write(`data: ${JSON.stringify(chunk)}\n\n`);
++   },
++ });
+```
+
+:::note
+
+The `writer` parameter passed to step `execute` functions is not affected by this change. It remains a `ToolStream` that extends `WritableStream<unknown>` and provides `.write()` and `.custom()` methods:
+
+```ts
+createStep({
+  id: 'my-step',
+  execute: async ({ writer }) => {
+    // This API is unchanged
+    await writer.write({ data: 'some output' });
+    await writer.custom({ type: 'custom-event', payload: {} });
+  },
+});
+```
+
+:::
+
+### `setState()` is now async and the data passed is validated
+
+The `setState()` function is now async. The data passed is now validated against the `stateSchema` defined in the step. The state data validation also uses the `validateInputs` flag to determine whether to validate the state data or not. Also, when calling `setState()`, you can now pass only the state data being updated, instead of adding the previous state spread `(...state)`.
+
+To migrate, update the `setState()` function to be async.
+
+```diff
+- setState({ ...state, sharedCounter: state.sharedCounter + 1 });
++ await setState({ sharedCounter: state.sharedCounter + 1 });
++ // await setState({ ...state, sharedCounter: state.sharedCounter + 1 }); 
++ // this also works, as the previous state spread remains supported
+```
+
 ## Removed
 
+### `streamVNext`, `resumeStreamVNext`, and `observeStreamVNext` methods
+
+The experimental `streamVNext()`, `resumeStreamVNext()`, and `observeStreamVNext()` methods have been removed. These methods are now the standard implementation with updated event structures and return types.
+
+To migrate, use the standard `stream()`, `resumeStream()`, and `observeStream()` methods. Update event type checks to use workflow-prefixed names and access stream properties directly.
+
+See [`Run.stream()`](/reference/v1/streaming/workflows/stream), [`Run.resumeStream()`](/reference/v1/streaming/workflows/resumeStream), and [`Run.observeStream()`](/reference/v1/streaming/workflows/observeStream) for details.
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/workflow-stream-vnext .
+```
+
+:::
+
+### `suspend` and `setState` are not available in step condition functions parameters
+
+The `suspend` and `setState` functions are not available in step condition functions parameters.
+
+To migrate, use the `suspend` function in the step execute function instead.
+
+```diff
+.dowhile(step, async ({ suspend, state, setState }) => {
+- setState({...state, updatedState: "updated state"})
+- await suspend({ reason: "Suspension reason" });
++ // Use the suspend/setState in the step execute function instead
+});
+```
+
+This is the same for `dountil` and `branch` condition functions parameters.
+
 ### Legacy workflows export
 
 The `./workflows/legacy` export path has been removed from `@mastra/core`. Legacy workflows are no longer supported.

package/.docs/raw/guides/migrations/vnext-to-standard-apis.mdx

@@ -160,7 +160,7 @@ The following options are available in the standard `.stream()` and `generate()`
           name: z.string(),
           age: z.number(),
         }),
-        model: "openai/gpt-4o-mini", // Optional model override for structuring
+        model: "openai/gpt-5.1", // Optional model override for structuring
         errorStrategy: "fallback",
         fallbackValue: { name: "unknown", age: 0 },
         instructions: "Extract user information", // Override default structuring instructions
@@ -300,7 +300,7 @@ The following options are available in the standard `.stream()` and `generate()`
       schema: z.object({
         summary: z.string(),
       }),
-      model: "openai/gpt-4o",
+      model: "openai/gpt-5.1",
     },
   });
   ```

package/.docs/raw/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: "About Mastra | Mastra Docs"
+title: "About Mastra"
 sidebar_position: 2
 sidebar_label: "Introduction"
 description: "Mastra is an all-in-one framework for building AI-powered applications and agents with a modern TypeScript stack."
@@ -27,7 +27,7 @@ Some highlights include:
 
 - [**Workflows**](/docs/v1/workflows/overview) - When you need explicit control over execution, use Mastra's graph-based workflow engine to orchestrate complex multi-step processes. Mastra workflows use an intuitive syntax for control flow (`.then()`, `.branch()`, `.parallel()`).
 
-- [**Human-in-the-loop**]/docs/v1/workflows/suspend-and-resume) - Suspend an agent or workflow and await user input or approval before resuming. Mastra uses [storage](/docs/v1/server-db/storage) to remember execution state, so you can pause indefinitely and resume where you left off.
+- [**Human-in-the-loop**](/docs/v1/workflows/suspend-and-resume) - Suspend an agent or workflow and await user input or approval before resuming. Mastra uses [storage](/docs/v1/server-db/storage) to remember execution state, so you can pause indefinitely and resume where you left off.
 
 - **Context management** - Give your agents the right context at the right time. Provide [conversation history](/docs/v1/memory/conversation-history), [retrieve](/docs/v1/rag/overview) data from your sources (APIs, databases, files), and add human-like [working](/docs/v1/memory/working-memory) and [semantic](/docs/v1/memory/semantic-recall) memory so your agents behave coherently.
 
@@ -51,8 +51,8 @@ Explore real-world examples in our [community showcase](/showcase).
 
 ## Get started
 
-Follow the [Installation guide](/docs/v1/getting-started/installation) for step-by-step setup with the CLI or a manual install.
+Choose a [getting started guide](/docs/v1/getting-started/start) to get started, or see the [manual installation guide](/docs/v1/getting-started/manual-install) if you need more control over your setup.
 
-If you're new to AI agents, check out our [templates](/docs/v1/getting-started/templates), [course](https://mastra.ai/book), and [YouTube videos](https://youtube.com/@mastra-ai) to start building with Mastra today.
+If you're new to AI agents, check out our [templates](https://mastra.ai/templates), [course](https://mastra.ai/course), and [YouTube videos](https://youtube.com/@mastra-ai). You can also join our [Discord](https://discord.gg/BTYqqHKUrf) community to get help and share your projects.
 
 We can't wait to see what you build ✌️

package/.docs/raw/mcp/overview.mdx

@@ -0,0 +1,358 @@
+---
+title: "MCP Overview | MCP"
+description: Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# MCP Overview
+
+Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open standard for connecting AI agents to external tools and resources. It serves as a universal plugin system, enabling agents to call tools regardless of language or hosting environment.
+
+Mastra can also be used to author MCP servers, exposing agents, tools, and other structured resources via the MCP interface. These can then be accessed by any system or agent that supports the protocol.
+
+Mastra currently supports two MCP classes:
+
+1. **`MCPClient`**: Connects to one or many MCP servers to access their tools, resources, prompts, and handle elicitation requests.
+2. **`MCPServer`**: Exposes Mastra tools, agents, workflows, prompts, and resources to MCP-compatible clients.
+
+## Getting started
+
+To use MCP, install the required dependency:
+
+```bash
+npm install @mastra/mcp@beta
+```
+
+## Configuring `MCPClient`
+
+The `MCPClient` connects Mastra primitives to external MCP servers, which can be local packages (invoked using `npx`) or remote HTTP(S) endpoints. Each server must be configured with either a `command` or a `url`, depending on how it's hosted.
+
+```typescript title="src/mastra/mcp/test-mcp-client.ts" showLineNumbers copy
+import { MCPClient } from "@mastra/mcp";
+
+export const testMcpClient = new MCPClient({
+  id: "test-mcp-client",
+  servers: {
+    wikipedia: {
+      command: "npx",
+      args: ["-y", "wikipedia-mcp"],
+    },
+    weather: {
+      url: new URL(
+        `https://server.smithery.ai/@smithery-ai/national-weather-service/mcp?api_key=${process.env.SMITHERY_API_KEY}`,
+      ),
+    },
+  },
+});
+```
+
+> See [MCPClient](/reference/v1/tools/mcp-client) for a full list of configuration options.
+
+## Using `MCPClient` with an agent
+
+To use tools from an MCP server in an agent, import your `MCPClient` and call `.getTools()` in the `tools` parameter. This loads from the defined MCP servers, making them available to the agent.
+
+```typescript {3,15} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
+import { Agent } from "@mastra/core/agent";
+
+import { testMcpClient } from "../mcp/test-mcp-client";
+
+export const testAgent = new Agent({
+  name: "Test Agent",
+  description: "You are a helpful AI assistant",
+  instructions: `
+      You are a helpful assistant that has access to the following MCP Servers.
+      - Wikipedia MCP Server
+      - US National Weather Service
+
+      Answer questions using the information you find using the MCP Servers.`,
+  model: "openai/gpt-5.1",
+  tools: await testMcpClient.getTools(),
+});
+```
+
+> See the [Agent Class](/reference/v1/agents/agent) for a full list of configuration options.
+
+## Configuring `MCPServer`
+
+To expose agents, tools, and workflows from your Mastra application to external systems over HTTP(S) use the `MCPServer` class. This makes them accessible to any system or agent that supports the protocol.
+
+```typescript title="src/mastra/mcp/test-mcp-server.ts" showLineNumbers copy
+import { MCPServer } from "@mastra/mcp";
+
+import { testAgent } from "../agents/test-agent";
+import { testWorkflow } from "../workflows/test-workflow";
+import { testTool } from "../tools/test-tool";
+
+export const testMcpServer = new MCPServer({
+  id: "test-mcp-server",
+  name: "Test Server",
+  version: "1.0.0",
+  agents: { testAgent },
+  tools: { testTool },
+  workflows: { testWorkflow },
+});
+```
+
+> See [MCPServer](/reference/v1/tools/mcp-server) for a full list of configuration options.
+
+## Registering an `MCPServer`
+
+To make an MCP server available to other systems or agents that support the protocol, register it in the main `Mastra` instance using `mcpServers`.
+
+```typescript title="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+
+import { testMcpServer } from "./mcp/test-mcp-server";
+
+export const mastra = new Mastra({
+  // ...
+  mcpServers: { testMcpServer },
+});
+```
+
+## Static and dynamic tools
+
+`MCPClient` offers two approaches to retrieving tools from connected servers, suitable for different application architectures:
+
+| Feature           | Static Configuration (`await mcp.getTools()`) | Dynamic Configuration (`await mcp.getToolsets()`)    |
+| :---------------- | :-------------------------------------------- | :--------------------------------------------------- |
+| **Use Case**      | Single-user, static config (e.g., CLI tool)   | Multi-user, dynamic config (e.g., SaaS app)          |
+| **Configuration** | Fixed at agent initialization                 | Per-request, dynamic                                 |
+| **Credentials**   | Shared across all uses                        | Can vary per user/request                            |
+| **Agent Setup**   | Tools added in `Agent` constructor            | Tools passed in `.generate()` or `.stream()` options |
+
+### Static tools
+
+Use the `.getTools()` method to fetch tools from all configured MCP servers. This is suitable when configuration (such as API keys) is static and consistent across users or requests. Call it once and pass the result to the `tools` property when defining your agent.
+
+> See [getTools()](/reference/v1/tools/mcp-client#gettools) for more information.
+
+```typescript {7} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
+import { Agent } from "@mastra/core/agent";
+
+import { testMcpClient } from "../mcp/test-mcp-client";
+
+export const testAgent = new Agent({
+  // ...
+  tools: await testMcpClient.getTools(),
+});
+```
+
+### Dynamic tools
+
+Use the `.getToolsets()` method when tool configuration may vary by request or user, such as in a multi-tenant system where each user provides their own API key. This method returns toolsets that can be passed to the `toolsets` option in the agent's `.generate()` or `.stream()` calls.
+
+```typescript {5-16,21} showLineNumbers copy
+import { MCPClient } from "@mastra/mcp";
+import { mastra } from "./mastra";
+
+async function handleRequest(userPrompt: string, userApiKey: string) {
+  const userMcp = new MCPClient({
+    servers: {
+      weather: {
+        url: new URL("http://localhost:8080/mcp"),
+        requestInit: {
+          headers: {
+            Authorization: `Bearer ${userApiKey}`,
+          },
+        },
+      },
+    },
+  });
+
+  const agent = mastra.getAgent("testAgent");
+
+  const response = await agent.generate(userPrompt, {
+    toolsets: await userMcp.getToolsets(),
+  });
+
+  await userMcp.disconnect();
+
+  return Response.json({
+    data: response.text,
+  });
+}
+```
+
+> See [getToolsets()](/reference/v1/tools/mcp-client#gettoolsets) for more information.
+
+## Connecting to an MCP registry
+
+MCP servers can be discovered through registries. Here's how to connect to some popular ones using `MCPClient`:
+
+<Tabs>
+  <TabItem value="klavis" label="Klavis AI">
+    [Klavis AI](https://klavis.ai) provides hosted, enterprise-authenticated, high-quality MCP servers.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        salesforce: {
+          url: new URL("https://salesforce-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
+        },
+        hubspot: {
+          url: new URL("https://hubspot-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
+        },
+      },
+    });
+    ```
+
+    Klavis AI offers enterprise-grade authentication and security for production deployments.
+
+    For more details on how to integrate Mastra with Klavis, check out their [documentation](https://docs.klavis.ai/documentation/ai-platform-integration/mastra).
+
+  </TabItem>
+  <TabItem value="mcp-run" label="mcp.run">
+    [mcp.run](https://www.mcp.run/) provides pre-authenticated, managed MCP servers. Tools are grouped into Profiles, each with a unique, signed URL.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        marketing: { // Example profile name
+          url: new URL(process.env.MCP_RUN_SSE_URL!), // Get URL from mcp.run profile
+        },
+      },
+    });
+    ```
+
+    > **Important:** Treat the mcp.run SSE URL like a password. Store it securely, for example, in an environment variable.
+    > ```bash title=".env"
+    > MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...
+    > ```
+
+  </TabItem>
+  <TabItem value="composio" label="Composio.dev">
+    [Composio.dev](https://composio.dev) offers a registry of [SSE-based MCP servers](https://mcp.composio.dev). You can use the SSE URL generated for tools like Cursor directly.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        googleSheets: {
+          url: new URL("https://mcp.composio.dev/googlesheets/[private-url-path]"),
+        },
+        gmail: {
+          url: new URL("https://mcp.composio.dev/gmail/[private-url-path]"),
+        },
+      },
+    });
+    ```
+
+    Authentication with services like Google Sheets often happens interactively through the agent conversation.
+
+    *Note: Composio URLs are typically tied to a single user account, making them best suited for personal automation rather than multi-tenant applications.*
+
+  </TabItem>
+  <TabItem value="smithery" label="Smithery.ai">
+    [Smithery.ai](https://smithery.ai) provides a registry accessible via their CLI.
+
+    ```typescript
+    // Unix/Mac
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        sequentialThinking: {
+          command: "npx",
+          args: [
+            "-y",
+            "@smithery/cli@latest",
+            "run",
+            "@smithery-ai/server-sequential-thinking",
+            "--config",
+            "{}",
+          ],
+        },
+      },
+    });
+    ```
+
+    ```typescript
+    // Windows
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        sequentialThinking: {
+          command: "npx",
+          args: [
+            "-y",
+            "@smithery/cli@latest",
+            "run",
+            "@smithery-ai/server-sequential-thinking",
+            "--config",
+            "{}",
+          ],
+        },
+      },
+    });
+    ```
+
+  </TabItem>
+  <TabItem value="ampersand" label="Ampersand">
+
+[Ampersand](https://withampersand.com?utm_source=mastra-docs) offers an [MCP Server](https://docs.withampersand.com/mcp) that allows you to connect your agent to 150+ integrations with SaaS products like Salesforce, Hubspot, and Zendesk.
+
+```typescript
+// MCPClient with Ampersand MCP Server using SSE
+export const mcp = new MCPClient({
+  servers: {
+    "@amp-labs/mcp-server": {
+      url: `https://mcp.withampersand.com/v1/sse?${new URLSearchParams({
+        apiKey: process.env.AMPERSAND_API_KEY,
+        project: process.env.AMPERSAND_PROJECT_ID,
+        integrationName: process.env.AMPERSAND_INTEGRATION_NAME,
+        groupRef: process.env.AMPERSAND_GROUP_REF,
+      })}`,
+    },
+  },
+});
+```
+
+```typescript
+// If you prefer to run the MCP server locally:
+import { MCPClient } from "@mastra/mcp";
+
+// MCPClient with Ampersand MCP Server using stdio transport
+export const mcp = new MCPClient({
+  servers: {
+    "@amp-labs/mcp-server": {
+      command: "npx",
+      args: [
+        "-y",
+        "@amp-labs/mcp-server@latest",
+        "--transport",
+        "stdio",
+        "--project",
+        process.env.AMPERSAND_PROJECT_ID,
+        "--integrationName",
+        process.env.AMPERSAND_INTEGRATION_NAME,
+        "--groupRef",
+        process.env.AMPERSAND_GROUP_REF, // optional
+      ],
+      env: {
+        AMPERSAND_API_KEY: process.env.AMPERSAND_API_KEY,
+      },
+    },
+  },
+});
+```
+
+As an alternative to MCP, Ampersand's AI SDK also has an adapter for Mastra, so you can [directly import Ampersand tools](https://docs.withampersand.com/ai-sdk#use-with-mastra) for your agent to access.
+
+  </TabItem>
+</Tabs>
+
+## Related
+
+- [Using Tools](/docs/v1/agents/using-tools)
+- [MCPClient](/reference/v1/tools/mcp-client)
+- [MCPServer](/reference/v1/tools/mcp-server)