@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.0

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

@@ -153,7 +153,6 @@ Step `suspendPayload` is now validated for steps that have a `suspendSchema` def
 -       return suspend({ reason: "Suspension reason" }); // Missing otherReason
 +       return suspend({ reason: "Suspension reason", otherReason: "Other reason" });
       }
-      //... continue execution logic
     },
   });
 ```
@@ -177,13 +176,54 @@ To migrate, update any code that consumes branch outputs to handle optional valu
 
 If your code depends on non-optional types, add runtime checks or provide default values when accessing branch outputs.
 
-### `setState` is now async and the data passed is validated
+### `writableStream` to `outputWriter` in `Run.start()` & `Run.timeTravel()`
 
-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`).
+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.
 
-To migrate, update the `setState` function to be async.
+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 });
@@ -293,7 +333,6 @@ createStep({
 +   if (!context.resumeData) {
 +     return context.suspend({})
 +   }
-+   //..continue execution logic
 + }
 });
 +
@@ -308,3 +347,7 @@ createStep({
 +   });
 + }
 ```
+
+### `sendEvent` API
+
+The `sendEvent` API has been removed from workflows. Use the suspend/resume API instead.

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

@@ -106,7 +106,7 @@ See the following API references for more information:
 
 No `format` option: Always return AI SDK v4 types
 
-```typescript showLineNumbers copy
+```typescript
 // Mastra native format (default)
 const result = await agent.stream(messages);
 ```
@@ -118,7 +118,7 @@ Use `format` option to choose output:
 - `'mastra'` (default)
 - `'aisdk'` (AI SDK v5 compatible)
 
-```typescript showLineNumbers copy
+```typescript
 // AI SDK v5 compatibility
 const result = await agent.stream(messages, {
   format: "aisdk",
@@ -131,7 +131,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `format` - Choose between 'mastra' or 'aisdk' output format:
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     format: "aisdk", // or 'mastra' (default)
   });
@@ -139,7 +139,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `system` - Custom system message (separate from instructions).
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     system: "You are a helpful assistant",
   });
@@ -153,7 +153,7 @@ The following options are available in the standard `.stream()` and `generate()`
     - 'error' - throw an error
     - 'fallback' - return a fallback value you provide
 
-    ```typescript showLineNumbers copy
+    ```typescript copy
     const result = await agent.generate(messages, {
       structuredOutput: {
         schema: z.object({
@@ -170,7 +170,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `stopWhen` - Flexible stop conditions (step count, token limit, etc).
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     stopWhen: ({ steps, totalTokens }) => steps >= 5 || totalTokens >= 10000,
   });
@@ -178,7 +178,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `providerOptions` - Provider-specific options (e.g., OpenAI-specific settings)
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     providerOptions: {
       openai: {
@@ -191,7 +191,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `onChunk` - Callback for each streaming chunk.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     onChunk: (chunk) => {
       console.log("Received chunk:", chunk);
@@ -201,7 +201,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `onError` - Error callback.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     onError: (error) => {
       console.error("Stream error:", error);
@@ -211,7 +211,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `onAbort` - Abort callback.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     onAbort: () => {
       console.log("Stream aborted");
@@ -221,7 +221,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `activeTools` - Specify which tools are active for this execution.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     activeTools: ["search", "calculator"], // Only these tools will be available
   });
@@ -229,7 +229,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `abortSignal` - AbortSignal for cancellation.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const controller = new AbortController();
   const result = await agent.stream(messages, {
     abortSignal: controller.signal,
@@ -240,7 +240,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `prepareStep` - Callback before each step in multi-step execution.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     prepareStep: ({ step, state }) => {
       console.log("About to execute step:", step);
@@ -253,7 +253,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `requireToolApproval` - Require approval for all tool calls.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     requireToolApproval: true,
   });
@@ -265,7 +265,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
   Unified in `modelSettings`
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     modelSettings: {
       temperature: 0.7,
@@ -279,7 +279,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
   Moved to memory object.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     memory: {
       resource: "user-123",
@@ -294,7 +294,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
   Use `structuredOutput` instead to allow for tool calls and an object return.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.generate(messages, {
     structuredOutput: {
       schema: z.object({
@@ -309,7 +309,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
   The `output` property is deprecated in favor of `structuredOutput`, to achieve the same results, omit the model and only pass `structuredOutput.schema`, optionally add `jsonPromptInjection: true` if your model does not natively support `response_format`.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.generate(messages, {
     structuredOutput: {
       schema: {
@@ -325,11 +325,9 @@ The following options are available in the standard `.stream()` and `generate()`
 
   Use `memory` instead.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.generate(messages, {
-    memory: {
-      // ...
-    },
+    memory: {},
   });
   ```
 
@@ -350,7 +348,7 @@ See the following API references for more information:
 
   `toolChoice` uses the AI SDK v5 `ToolChoice` type.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   type ToolChoice<TOOLS extends Record<string, unknown>> =
     | "auto"
     | "none"

package/.docs/raw/index.mdx

@@ -27,9 +27,9 @@ 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 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.
+- **Context management** - Give your agents the right context at the right time. Provide [message history](/docs/v1/memory/message-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.
 
 - **Integrations** - Bundle agents and workflows into existing React, Next.js, or Node.js apps, or ship them as standalone endpoints. When building UIs, integrate with agentic libraries like Vercel's AI SDK UI and CopilotKit to bring your AI assistant to life on the web.
 

package/.docs/raw/mastra-cloud/deployment.mdx

@@ -0,0 +1,86 @@
+---
+title: "Deployment | Mastra Cloud"
+description: Deploy your Mastra application to production
+---
+
+# Deployment
+
+Deploy your Mastra application to production and expose your agents, tools, and workflows as REST API endpoints.
+
+:::info
+Mastra Cloud is currently in beta, but many teams are already using it to deploy their agents. It's the easiest way to run Mastra agents in a managed environment.
+:::
+
+## Enable deployments
+
+After [setting up your project](/docs/v1/mastra-cloud/setup), click **Deployment** in the sidebar and select **Enable Deployments**.
+
+Once enabled, your project automatically builds and deploys. Future pushes to your main branch trigger automatic redeployments.
+
+## Dashboard
+
+The **Overview** page shows your project's domain URL, status, latest deployment, and connected agents and workflows.
+
+![Project dashboard](/img/mastra-cloud/mastra-cloud-project-dashboard.jpg)
+
+Click the **Deployments** menu item to view build logs. Open **Settings** to configure environment variables, branch, storage, and endpoint URLs. 
+
+:::note
+Changes to settings require a new deployment to take effect
+:::
+
+## Storage configuration
+
+Mastra Cloud offers two storage options:
+
+1. **Mastra Cloud Store**: Managed storage provided by Mastra Cloud
+1. **Bring your own database**: Connect to your own external database
+
+### Using Mastra Cloud Store
+
+When using the managed Mastra Cloud Store (enabled in your project settings), storage must be configured on the `Mastra` instance, not on individual agent `Memory` instances.
+
+Configure storage on your Mastra instance:
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: "mastra-store",
+    url: "file:./mastra.db",
+  }),
+  agents: { myAgent },
+});
+```
+
+Agents can use Memory without specifying storage as they inherit from the Mastra instance:
+
+```typescript title="src/mastra/agents/my-agent.ts"
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+
+export const myAgent = new Agent({
+  id: "my-agent",
+  memory: new Memory({
+    // No storage here - uses instance-level storage from Mastra Cloud Store
+    options: {
+      lastMessages: 20,
+    },
+  }),
+});
+```
+
+### Bring your own database
+
+If you don't use Mastra Cloud Store, you can use any [storage provider](/docs/v1/memory/storage#supported-providers) with any configuration. Set your database connection strings as environment variables in your project's **Settings** page.
+
+## Using your deployment
+
+After deployment, interact with your agents using the [Mastra Client](/docs/v1/server/mastra-client) or call the REST API endpoints directly.
+
+## Next steps
+
+- [Studio](/docs/v1/mastra-cloud/studio) - Test your agents in the cloud
+- [Observability](/docs/v1/mastra-cloud/observability) - Monitor traces and logs

package/.docs/raw/mastra-cloud/observability.mdx

@@ -0,0 +1,43 @@
+---
+title: "Observability | Mastra Cloud"
+description: Monitoring and debugging tools for Mastra Cloud deployments
+---
+
+# Observability
+
+Cloud provides observability for production applications, giving you insight into how your agents and workflows behave. Observability works whether your application is deployed to Mastra Cloud, running locally, or hosted on your own infrastructure. Any Mastra project can send traces and logs to the platform regardless of where it's running.
+
+For details on configuring observability, see the [Cloud Exporter](/docs/v1/observability/tracing/exporters/cloud) docs.
+
+## Traces
+
+Traces are available for both agents and workflows by enabling [observability](/docs/v1/observability/tracing/overview) using one of the [supported providers](/docs/v1/observability/tracing/overview#exporters).
+
+### Agents
+
+With observability enabled, you can view detailed outputs from your agents in the **Traces** section in [Studio](/docs/v1/mastra-cloud/studio).
+
+![observability agents](/img/mastra-cloud/mastra-cloud-observability-agents.jpg)
+
+Agent traces break a run into clear steps: model calls, tool calls, and intermediate chunks. Each includes timing, inputs, outputs, and errors. Drill into any span to inspect prompts, token usage, and results.
+
+### Workflows
+
+With observability enabled, you can view detailed outputs from your workflows in the **Traces** section in [Studio](/docs/v1/mastra-cloud/studio).
+
+![observability workflows](/img/mastra-cloud/mastra-cloud-observability-workflows.jpg)
+
+Workflow traces capture each step in the run, including transitions, branching, timing, and any tool calls. Inspect inputs, outputs, and errors for every step to debug long-running or multi-step processes.
+
+## Logs
+
+The **Logs** page in the [project dashboard](/docs/v1/mastra-cloud/deployment#dashboard) displays detailed information for debugging and monitoring your application's behavior.
+
+![Dashboard logs](/img/mastra-cloud/mastra-cloud-dashboard-logs.jpg)
+
+Each log entry includes its severity level and a detailed message showing agent, workflow, or storage activity.
+
+## Next steps
+
+- [Logging](/docs/v1/observability/logging)
+- [Tracing](/docs/v1/observability/tracing/overview)

package/.docs/raw/mastra-cloud/overview.mdx

@@ -0,0 +1,31 @@
+---
+title: "Mastra Cloud | Mastra Cloud"
+description: Deployment and monitoring service for Mastra applications
+---
+
+# Mastra Cloud
+
+[Mastra Cloud](https://cloud.mastra.ai) is a platform for deploying, managing, and monitoring Mastra applications. [Import your project](/docs/v1/mastra-cloud/setup) to get started.
+
+## Studio
+
+Run [Studio](/docs/v1/mastra-cloud/studio) in the cloud and share access with your team via a link. Team members can test agents and workflows, tweak system prompts, and give feedback without running the project locally.
+
+## Deploy
+
+Enable [deployments](/docs/v1/mastra-cloud/deployment) and Mastra Cloud hosts your server for you. Connect your GitHub repository for automatic deployments whenever you push to your configured branch. Mastra Cloud exposes your agents, tools, and workflows as REST API endpoints.
+
+Once deployed, the project dashboard gives you visibility into:
+
+- Deployment status and history
+- Build logs and configuration
+- Environment variables and settings
+
+## Observability
+
+[Observability](/docs/v1/mastra-cloud/observability) provides insight into how your agents and workflows behave in production. View detailed traces of agent runs, workflow executions, and logs to debug issues and understand performance.
+
+:::info
+You don’t need to deploy to Mastra Cloud to use Observability. You can send traces to Mastra from any environment
+:::
+

package/.docs/raw/mastra-cloud/setup.mdx

@@ -0,0 +1,64 @@
+---
+title: "Setup | Mastra Cloud"
+description: Import your Mastra project to Mastra Cloud
+---
+
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+
+# Setup
+
+Import your Mastra project to [Mastra Cloud](https://cloud.mastra.ai) to use [Studio](/docs/v1/mastra-cloud/studio) and optionally [deploy](/docs/v1/mastra-cloud/deployment) your agent.
+
+## Before you begin
+
+- [Sign in](https://cloud.mastra.ai) to Cloud
+- Push your [Mastra project](/docs/v1/getting-started/start) to GitHub
+
+## Options
+
+
+![Select project type](/img/mastra-cloud/mastra-cloud-select.png)
+
+When you create a new project, you can choose from three options:
+
+1. **Create from GitHub** - Import a Mastra project from GitHub
+2. **Create from your server** - Connect a self-hosted Mastra instance to [Studio](/docs/v1/mastra-cloud/studio)
+3. **Create from template** - Start from a [pre-built template](https://mastra.ai/templates)
+
+
+To create a project from GitHub, follow these steps:
+
+## Create from GitHub
+
+<Steps>
+
+<StepItem>
+Connect to GitHub when prompted
+
+![Deployment details](/img/mastra-cloud/mastra-cloud-connect.png)
+</StepItem>
+
+<StepItem>
+Search for your repository and click **Import**
+
+![Deployment details](/img/mastra-cloud/mastra-cloud-import-git-repository.jpg)
+</StepItem>
+
+<StepItem>
+Configure your project settings. Mastra Cloud auto-detects most settings, but you'll still need to enter the environment variables for your configured [model provider](/models/v1):
+
+![Deployment details](/img/mastra-cloud/mastra-cloud-deployment-details.jpg)
+</StepItem>
+
+<StepItem>
+
+Click **Create Project**
+</StepItem>
+</Steps>
+
+## Next steps
+
+Once your project is imported, [Studio](/docs/v1/mastra-cloud/studio) automatically creates a sandbox where you can interact with your agents and share access with your team.
+
+When you're ready for production, enable [Deployment](/docs/v1/mastra-cloud/deployment) settings and hit deploy!

package/.docs/raw/mastra-cloud/studio.mdx

@@ -0,0 +1,35 @@
+---
+title: "Studio | Mastra Cloud"
+description: Run Studio in the cloud for team collaboration
+---
+
+import YouTube from "@site/src/components/YouTube-player";
+
+# Studio
+
+<YouTube id="ojGu6Bi4wYk" />
+
+Mastra Cloud provides a hosted version of [Studio](/docs/v1/getting-started/studio) that gives your team a shared environment for interacting with and testing your agents. Team members can chat with agents, review traces, give feedback, and tweak system prompts - without needing to run the project locally.
+
+[Set up your project](/docs/v1/mastra-cloud/setup) to access Studio in the cloud.
+
+See the [Studio documentation](/docs/v1/getting-started/studio) for details on features like the Agents playground, Workflows runner, Tools testing, and MCP Servers.
+
+:::note
+You don't need to deploy your agent to use Studio. Studio runs in a sandbox environment separate from your production deployment
+:::
+
+## Sharing access
+
+To invite team members, go to [Mastra Cloud](https://cloud.mastra.ai), click **Team Settings**, then **Members** to add them. Once invited, they can sign in and access your project's Studio.
+
+![Invite team members](/img/mastra-cloud/mastra-cloud-invite.png)
+
+:::warning
+Team members can view environment variables and delete projects. Only invite people you trust.
+:::
+
+## Next steps
+
+- [Deployment](/docs/v1/mastra-cloud/deployment) - Manage deployments and settings
+- [Observability](/docs/v1/mastra-cloud/observability) - Monitor traces and logs