@mastra/mcp-docs-server 0.13.2-alpha.0 → 0.13.2-alpha.2

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

@@ -0,0 +1,100 @@
+---
+title: Understanding the Mastra Cloud Dashboard
+description: Details of each feature available in Mastra Cloud
+---
+
+import { MastraCloudCallout } from '@/components/mastra-cloud-callout'
+
+# Navigating the Dashboard
+
+This page explains how to navigate the Mastra Cloud dashboard, where you can configure your project, view deployment details, and interact with agents and workflows using the built-in [Playground](/docs/mastra-cloud/dashboard#playground).
+
+<MastraCloudCallout />
+
+## Overview
+
+The **Overview** page provides details about your application, including its domain URL, status, latest deployment, and connected agents and workflows.
+
+![Project dashboard](/image/mastra-cloud/mastra-cloud-project-dashboard.jpg)
+
+Key features:
+
+Each project shows its current deployment status, active domains, and environment variables, so you can quickly understand how your application is running.
+
+## Deployments
+
+The **Deployments** page shows recent builds and gives you quick access to detailed build logs. Click any row to view more information about a specific deployment.
+
+![Dashboard deployment](/image/mastra-cloud/mastra-cloud-dashboard-deployments.jpg)
+
+Key features:
+
+Each deployment includes its current status, the Git branch it was deployed from, and a title generated from the commit hash.
+
+## Logs
+
+The **Logs** page is where you'll find detailed information to help debug and monitor your application's behavior in the production environment.
+
+![Dashboard logs](/image/mastra-cloud/mastra-cloud-dashboard-logs.jpg)
+
+Key features:
+
+Each log includes a severity level and detailed messages showing agent, workflow, and storage activity.
+
+## Settings
+
+On the **Settings** page you can modify the configuration of your application.
+
+![Dashboard settings](/image/mastra-cloud/mastra-cloud-dashboard-settings.jpg)
+
+Key features:
+
+You can manage environment variables, edit key project settings like the name and branch, configure storage with LibSQLStore, and set a stable URL for your endpoints.
+
+> Changes to configuration require a new deployment before taking effect.
+
+## Playground
+
+### Agents
+
+On the **Agents** page you'll see all agents used in your application. Click any agent to interact using the chat interface.
+
+![Dashboard playground agents](/image/mastra-cloud/mastra-cloud-dashboard-playground-agents.jpg)
+
+Key features:
+
+Test your agents in real time using the chat interface, review traces of each interaction, and see evaluation scores for every response.
+
+### Workflows
+
+On the **Workflows** page you'll see all workflows used in your application. Click any workflow to interact using the runner interface.
+
+![Dashboard playground workflows](/image/mastra-cloud/mastra-cloud-dashboard-playground-workflows.jpg)
+
+Key features:
+
+Visualize your workflow with a step-by-step graph, view execution traces, and run workflows directly using the built-in runner.
+
+### Tools
+
+On the **Tools** page you'll see all tools used by your agents. Click any tool to interact using the input interface.
+
+![Dashboard playground tools](/image/mastra-cloud/mastra-cloud-dashboard-playground-tools.jpg)
+
+Key features:
+
+Test your tools by providing an input that matches the schema and viewing the structured output.
+
+## MCP Servers
+
+The **MCP Servers** page lists all MCP Servers included in your application. Click any MCP Server for more information.
+
+![Dashboard playground mcp servers](/image/mastra-cloud/mastra-cloud-dashboard-playground-mcpservers.jpg)
+
+Key features:
+
+Each MCP Server includes API endpoints for HTTP and SSE, along with IDE configuration snippets for tools like Cursor and Windsurf.
+
+## Next steps
+
+- [Understanding Tracing and Logs](/docs/mastra-cloud/observability)

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

@@ -3,164 +3,50 @@ title: Observability in Mastra Cloud
 description: Monitoring and debugging tools for Mastra Cloud deployments
 ---
 
-# Observability in Mastra Cloud
+import { MastraCloudCallout } from '@/components/mastra-cloud-callout'
 
-> **Beta Notice**
-> Mastra Cloud is currently in **beta**.
+# Understanding Tracing and Logs
 
-Mastra Cloud records execution data for monitoring and debugging. It captures traces, logs, and runtime information from agents and workflows.
+Mastra Cloud captures execution data to help you monitor your application's behavior in the production environment.
 
-## Agent Interface
+<MastraCloudCallout />
 
-The agent interface offers three main views, accessible via tabs:
-
-1. **Chat**: Interactive messaging interface to test your agent
-2. **Traces**: Detailed execution records
-3. **Evaluation**: Agent performance assessment
-
-![Agent Interface with Chat Tab](../../../../../public/image/cloud-agent.png)
-
-### Chat Interface
-
-The Chat tab provides:
-
-- Interactive messaging with deployed agents
-- System response to user queries
-- Suggested prompt buttons (e.g., "What capabilities do you have?")
-- Message input area
-- Branch indicator (e.g., "main")
-- Note about agent memory limitations
-
-### Agent Configuration Panel
-
-The right sidebar displays agent details:
-
-- Agent name and deployment identifier
-- Model information (e.g., "OpenAI")
-- Tools available to the agent (e.g., "getWeather")
-- Complete system prompt text
-
-This panel provides visibility into how the agent is configured without needing to check the source code.
-
-## Trace System
-
-Mastra Cloud records traces for agent and workflow interactions.
-
-### Trace Explorer Interface
-
-![Agent Traces View](/image/cloud-agent-traces.png)
-
-The Trace Explorer interface shows:
-
-- All agent and workflow interactions
-- Specific trace details
-- Input and output data
-- Tool calls with parameters and results
-- Workflow execution paths
-- Filtering options by type, status, timestamp, and agent/workflow
-
-### Trace Data Structure
-
-Each trace contains:
-
-1. **Request Data**: The request that initiated the agent or workflow
-2. **Tool Call Records**: Tool calls during execution with parameters
-3. **Tool Response Data**: The responses from tool calls
-4. **Agent Response Data**: The generated agent response
-5. **Execution Timestamps**: Timing information for each execution step
-6. **Model Metadata**: Information about model usage and tokens
-
-The trace view displays all API calls and results throughout execution. This data helps debug tool usage and agent logic flows.
-
-### Agent Interaction Data
-
-Agent interaction traces include:
-
-- User input text
-- Agent processing steps
-- Tool calls (e.g., weather API calls)
-- Parameters and results for each tool call
-- Final agent response text
-
-## Dashboard Structure
-
-The Mastra Cloud dashboard contains:
-
-- Project deployment history
-- Environment variable configuration
-- Agent configuration details (model, system prompt, tools)
-- Workflow step visualization
-- Deployment URLs
-- Recent activity log
-
-## Agent Testing
-
-Test your agents using the Chat interface:
-
-1. Navigate to the Agents section
-2. Select the agent you want to test
-3. Use the Chat tab to interact with your agent
-4. Send messages and view responses
-5. Use suggested prompts for common queries
-6. Switch to the Traces tab to view execution details
-
-Note that by default, agents do not remember conversation history across sessions. The interface indicates this with the message: "Agent will not remember previous messages. To enable memory for agent see image."
+## Logs
 
-## Workflow Monitoring
+You can view detailed logs for debugging and monitoring your application's behavior on the [Logs](/docs/mastra-cloud/dashboard#logs) page of the Dashboard.
 
-![Workflow Interface](/image/cloud-workflow.png)
+![Dashboard logs](/image/mastra-cloud/mastra-cloud-dashboard-logs.jpg)
 
-Workflow monitoring shows:
+Key features:
 
-- Diagram of workflow steps and connections
-- Status for each workflow step
-- Execution details for each step
-- Execution trace records
-- Multi-step process execution (e.g., weather lookup followed by activity planning)
+Each log entry includes its severity level and a detailed message showing agent, workflow, or storage activity.
 
-### Workflow Execution
+## Traces
 
-![Workflow Run Details](/image/cloud-workflow-run.png)
+More detailed traces are available for both agents and workflows by using a [logger](/docs/observability/logging) or enabling [telemetry](/docs/observability/tracing) using one of our [supported providers](/reference/observability/providers).
 
-When examining a specific workflow execution, you can see the detailed steps and their outputs.
+### Agents
 
-## Logs
+With a [logger](/docs/observability/logging) enabled, you can view detailed outputs from your agents in the **Traces** section of the Agents Playground.
 
-![Logs Interface](/image/cloud-logs.png)
+![observability agents](/image/mastra-cloud/mastra-cloud-observability-agents.jpg)
 
-The Logs section provides detailed information about your application:
+Key features:
 
-- **Time**: When the log entry was created
-- **Level**: Log level (info, debug)
-- **Hostname**: Server identification
-- **Message**: Detailed log information, including:
-  - API initialization
-  - Storage connections
-  - Agent and workflow activity
+Tools passed to the agent during generation are standardized using `convertTools`. This includes retrieving client-side tools, memory tools, and tools exposed from workflows.
 
-## Technical Features
 
-The observability system includes:
+### Workflows
 
-- **API Endpoints**: For programmatic access to trace data
-- **Structured Trace Format**: JSON format for filtering and query operations
-- **Historical Data Storage**: Retention of past execution records
-- **Deployment Version Links**: Correlation between traces and deployment versions
+With a [logger](/docs/observability/logging) enabled, you can view detailed outputs from your workflows in the **Traces** section of the Workflows Playground.
 
-## Debugging Patterns
+![observability workflows](/image/mastra-cloud/mastra-cloud-observability-workflows.jpg)
 
-- Compare trace data when testing agent behavior changes
-- Use the chat interface to test edge case inputs
-- View system prompts to understand agent behavior
-- Examine tool call parameters and results
-- Verify workflow execution step sequencing
-- Identify execution bottlenecks in trace timing data
-- Compare trace differences between agent versions
+Key features:
 
-## Support Resources
+Workflows are created using `createWorkflow`, which sets up steps, metadata, and tools. You can run them with `runWorkflow` by passing input and options.
 
-For technical assistance with observability:
+## Next steps
 
-- Review the [Troubleshooting Documentation]()
-- Contact technical support through the dashboard
-- Join the [Discord developer channel](https://discord.gg/mastra)
+- [Logging](/docs/observability/logging)
+- [Tracing](/docs/observability/tracing)

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

@@ -3,61 +3,69 @@ title: Mastra Cloud
 description: Deployment and monitoring service for Mastra applications
 ---
 
+import { MastraCloudCallout } from '@/components/mastra-cloud-callout'
+import { FileTree } from "nextra/components";
+
 # Mastra Cloud
 
-Mastra Cloud is a deployment service built by the Mastra team that runs,
-manages, and monitors Mastra applications. It works with standard Mastra
-projects and handles deployment, scaling, and operational tasks.
+[Mastra Cloud](https://mastra.ai/cloud) is a platform for deploying, managing, monitoring, and debugging Mastra applications. When you [deploy](/docs/mastra-cloud/setting-up) your application, Mastra Cloud exposes your agents, tools, and workflows as REST API endpoints.
+
+<MastraCloudCallout />
+
+## Platform features
+
+Deploy and manage your applications with automated builds, organized projects, and no additional configuration.
+
+![Platform features](/image/mastra-cloud/mastra-cloud-platform-features.jpg)
+
+Key features:
+
+Mastra Cloud supports zero-config deployment, continuous integration with GitHub, and atomic deployments that package agents, tools, and workflows together.
 
-> **Beta Notice**
-> Mastra Cloud is currently in **public beta**. Features, APIs, and UIs may
-> change as development continues.
+## Project Dashboard
 
-## Core Functionality
+Monitor and debug your applications with detailed output logs, deployment state, and interactive tools.
 
-- **Atomic Deployments** - Agents and workflows deploy as a single unit
-- **Project Organization** - Group agents and workflows into projects with assigned URLs
-- **Environment Variables** - Store configuration securely by environment
-- **Testing Console** - Send messages to agents through a web interface
-- **Execution Tracing** - Record agent interactions and tool calls
-- **Workflow Visualization** - Display workflow steps and execution paths
-- **Logs** - Standard logging output for debugging
-- **Platform Compatibility** - Uses the same infrastructure as Cloudflare, Vercel, and Netlify deployers
+![Project dashboard](/image/mastra-cloud/mastra-cloud-project-dashboard.jpg)
 
-## Dashboard Components
+Key features:
 
-The Mastra Cloud dashboard contains:
+The Project Dashboard gives you an overview of your application's status and deployments, with access to logs and a built-in playground for testing agents and workflows.
 
-- **Projects List** - All projects in the account
-- **Project Details** - Deployments, environment variables, and access URLs
-- **Deployment History** - Record of deployments with timestamps and status
-- **Agent Inspector** - Agent configuration view showing models, tools, and system prompts
-- **Testing Console** - Interface for sending messages to agents
-- **Trace Explorer** - Records of tool calls, parameters, and responses
-- **Workflow Viewer** - Diagram of workflow steps and connections
+## Project structure
 
-## Technical Implementation
+Use a standard Mastra project structure for proper detection and deployment.
 
-Mastra Cloud runs on the same core code as the platform-specific deployers with these modifications:
+<FileTree>
+  <FileTree.Folder name="src" defaultOpen>
+    <FileTree.Folder name="mastra" defaultOpen>
+      <FileTree.Folder name="agents" defaultOpen>
+        <FileTree.File name="agent-name.ts" />
+      </FileTree.Folder>
+      <FileTree.Folder name="tools" defaultOpen>
+        <FileTree.File name="tool-name.ts" />
+      </FileTree.Folder>
+      <FileTree.Folder name="workflows" defaultOpen>
+        <FileTree.File name="workflow-name.ts" />
+      </FileTree.Folder>
+      <FileTree.File name="index.ts" />
+    </FileTree.Folder>
+  </FileTree.Folder>
+  <FileTree.File name="package.json" />
+</FileTree>
 
-- **Edge Network Distribution** - Geographically distributed execution
-- **Dynamic Resource Allocation** - Adjusts compute resources based on traffic
-- **Mastra-specific Runtime** - Runtime optimized for agent execution
-- **Standard Deployment API** - Consistent deployment interface across environments
-- **Tracing Infrastructure** - Records all agent and workflow execution steps
+Mastra Cloud scans your repository for:
 
-## Use Cases
+- **Agents**: Defined using: `new Agent({...})`
+- **Tools**: Defined using: `createTool({...})`
+- **Workflows**: Defined using: `createWorkflow({...})`
+- **Steps**: Defined using: `createStep({...})`
+- **Environment Variables**: API keys and configuration variables
 
-Common usage patterns:
+## Technical implementation
 
-- Deploying applications without managing infrastructure
-- Maintaining staging and production environments
-- Monitoring agent behavior across many requests
-- Testing agent responses through a web interface
-- Deploying to multiple regions
+Mastra Cloud is purpose-built for Mastra agents, tools, and workflows. It handles long-running requests, records detailed traces for every execution, and includes built-in support for evals.
 
-## Setup Process
+## Next steps
 
-1. [Configure a Mastra Cloud project](/docs/mastra-cloud/setting-up)
-2. [Deploy code](/docs/mastra-cloud/deploying)
-3. [View execution traces](/docs/mastra-cloud/observability)
+- [Setting Up and Deploying](/docs/mastra-cloud/setting-up)

package/.docs/raw/mastra-cloud/setting-up.mdx

@@ -3,126 +3,90 @@ title: Setting Up a Project
 description: Configuration steps for Mastra Cloud projects
 ---
 
-# Setting Up a Mastra Cloud Project
+import { MastraCloudCallout } from '@/components/mastra-cloud-callout'
+import { Steps } from "nextra/components";
 
-> **Beta Notice**
-> Mastra Cloud is currently in **beta**.
+# Setting Up and Deploying
 
-This page describes the steps to set up a project on Mastra Cloud using GitHub integration.
+This page explains how to set up a project on [Mastra Cloud](https://mastra.ai/cloud) with automatic deployments using our GitHub integration.
 
-## Prerequisites
-
-- A Mastra Cloud account
-- A GitHub account
-- A GitHub repository containing a Mastra application
+<MastraCloudCallout />
 
-## Project Creation Process
-
-1. **Sign in to Mastra Cloud**
+## Prerequisites
 
-   - Navigate to the Mastra Cloud dashboard at https://cloud.mastra.ai
-   - Sign in with your account credentials
+- A [Mastra Cloud](https://mastra.ai/cloud) account
+- A GitHub account / repository containing a Mastra application
 
-2. **Add a New Project**
+> See our [Getting started](/docs/getting-started/installation) guide to scaffold out a new Mastra project with sensible defaults.
 
-   - From the "All Projects" view, click the "Add new" button in the top right
-   - This opens the GitHub repository import dialog
+## Setup and Deploy process
 
-   ![Mastra Cloud Projects Dashboard](/image/cloud-agents.png)
+<Steps>
 
-3. **Import Git Repository**
+### Sign in to Mastra Cloud
 
-   - Search for repositories or select from the list of available GitHub repositories
-   - Click the "Import" button next to the repository you want to deploy
+Head over to [https://cloud.mastra.ai/](https://cloud.mastra.ai) and sign in with either:
 
-4. **Configure Deployment Details**
-   The deployment configuration page includes:
-   - **Repo Name**: The GitHub repository name (read-only)
-   - **Project Name**: Customize the project name (defaults to repo name)
-   - **Branch**: Select the branch to deploy (dropdown, defaults to `main`)
-   - **Project root**: Set the root directory of your project (defaults to `/`)
-   - **Mastra Directory**: Specify where Mastra files are located (defaults to `src/mastra`)
-   - **Build Command**: Optional command to run during build process
-   - **Store Settings**: Configure data storage options
-   - **Environment Variables**: Add key-value pairs for configuration (e.g., API keys)
+- **GitHub**
+- **Google**
 
-## Project Structure Requirements
+### Install the Mastra GitHub app
 
-Mastra Cloud scans the GitHub repository for:
+When prompted, install the Mastra GitHub app.
 
-- **Agents**: Agent definitions (e.g., Weather Agent) with models and tools
-- **Workflows**: Workflow step definitions (e.g., weather-workflow)
-- **Environment Variables**: Required API keys and configuration variables
+![Install GitHub](/image/mastra-cloud/mastra-cloud-install-github.jpg)
 
-The repository should contain a standard Mastra project structure for proper detection and deployment.
+### Create a new project
 
-## Understanding the Dashboard
+Click the **Create new project** button to create a new project.
 
-After creating a project, the dashboard shows:
+![Create new project](/image/mastra-cloud/mastra-cloud-create-new-project.jpg)
 
-### Project Overview
+### Import a Git repository
 
-- **Created Date**: When the project was created
-- **Domains**: URLs for accessing your deployed application
-  - Format: `https://[project-name].mastra.cloud`
-  - Format: `https://[random-id].mastra.cloud`
-- **Status**: Current deployment status (success or archived)
-- **Branch**: The branch deployed (typically `main`)
-- **Environment Variables**: Configured API keys and settings
-- **Workflows**: List of detected workflows with step counts
-- **Agents**: List of detected agents with models and tools
-- **Database Usage**: Reads, writes, and storage statistics
+Search for a repository, then click **Import**.
 
-### Deployments Section
+![Import Git repository](/image/mastra-cloud/mastra-cloud-import-git-repository.jpg)
 
-- List of all deployments with:
-  - Deployment ID (based on commit hash)
-  - Status (success/archived)
-  - Branch
-  - Commit hash
-  - Timestamp
+### Configure the deployment
 
-### Logs Section
+Mastra Cloud automatically detects the right build settings, but you can customize them using the options described below.
 
-The Logs view displays:
+![Deployment details](/image/mastra-cloud/mastra-cloud-deployment-details.jpg)
 
-- Timestamp for each log entry
-- Log level (info, debug)
-- Hostname
-- Detailed log messages, including:
-  - API startup information
-  - Storage initialization
-  - Agent and workflow activity
+- **Importing from GitHub**: The GitHub repository name
+- **Project name**: Customize the project name
+- **Branch**: The branch to deploy from
+- **Project root**: The root directory of your project
+- **Mastra directory**: Where Mastra files are located
+- **Environment variables**: Add environment variables used by the application
+- **Build and Store settings**:
+   - **Install command**: Runs pre-build to install project dependencies
+   - **Project setup command**: Runs pre-build to prepare any external dependencies
+   - **Port**: The network port the server will use
+   - **Store settings**: Use Mastra Cloud's built-in [LibSQLStore](/docs/storage/overview) storage
+- **Deploy Project**: Starts the deployment process
 
-## Navigation
+### Deploy project
 
-The sidebar provides access to:
+Click **Deploy Project** to create and deploy your application using the configuration you’ve set.
 
-- **Overview**: Project summary and statistics
-- **Deployments**: Deployment history and details
-- **Logs**: Application logs for debugging
-- **Agents**: List and configuration of all agents
-- **Workflows**: List and structure of all workflows
-- **Settings**: Project configuration options
+</Steps>
 
-## Environment Variable Configuration
+## Successful deployment
 
-Set environment variables through the dashboard:
+After a successful deployment you'll be shown the **Overview** screen where you can view your project's status, domains, latest deployments and connected agents and workflows.
 
-1. Navigate to your project in the dashboard
-2. Go to the "Environment Variables" section
-3. Add or edit variables (such as `OPENAI_API_KEY`)
-4. Save the configuration
+![Successful deployment](/image/mastra-cloud/mastra-cloud-successful-deployment.jpg)
 
-Environment variables are encrypted and made available to your application during deployment and execution.
+## Continuous integration
 
-## Testing Your Deployment
+Your project is now configured with automatic deployments which occur whenever you push to the configured branch of your GitHub repository.
 
-After deployment, you can test your agents and workflows using:
+## Testing your application
 
-1. The custom domain assigned to your project: `https://[project-name].mastra.cloud`
-2. The dashboard interface for direct interaction with agents
+After a successful deployment you can test your agents and workflows from the [Playground](/docs/mastra-cloud/dashboard#playground) in Mastra Cloud, or interact with them using our [Client SDK](/docs/client-js/overview).
 
-## Next Steps
+## Next steps
 
-After setting up your project, automatic deployments occur whenever you push to the `main` branch of your GitHub repository. See the [deployment documentation](./deploying.mdx) for more details.
+- [Navigating the Dashboard](/docs/mastra-cloud/dashboard)

package/.docs/raw/memory/overview.mdx

@@ -8,6 +8,8 @@ The context window is the total information visible to the language model at any
 
 In Mastra, context is broken up into three parts: system instructions and information about the user ([working memory](./working-memory.mdx)), recent messages ([message history](#conversation-history)), and older messages that are relevant to the user’s query ([semantic recall](./semantic-recall.mdx)).
 
+Working memory can persist at different scopes - either per conversation thread (default) or across all threads for the same user (resource-scoped), enabling persistent user profiles that remember context across conversations.
+
 In addition, we provide [memory processors](./memory-processors.mdx) to trim context or remove information if the context is too long.
 
 ## Quick Start
@@ -69,6 +71,8 @@ Mastra organizes memory into threads, which are records that identify specific c
 1.  **`threadId`**: A specific conversation id (e.g., `support_123`).
 2.  **`resourceId`**: The user or entity id that owns each thread (e.g., `user_123`, `org_456`).
 
+The `resourceId` is particularly important for [resource-scoped working memory](./working-memory.mdx#resource-scoped-memory), which allows memory to persist across all conversation threads for the same user.
+
 ```typescript {2,3}
 const response = await myMemoryAgent.stream("Hello, my name is Alice.", {
   resourceId: "user_alice",