@mastra/mcp-docs-server 0.13.1 → 0.13.2-alpha.1

package/.docs/raw/local-dev/mastra-dev.mdx

@@ -1,172 +1,170 @@
 ---
-title: "Inspecting Agents with `mastra dev` | Mastra Local Dev Docs"
+title: "Inspecting agents and workflows with mastra dev | Mastra Local Dev Docs"
 description: Documentation for the Mastra local development environment for Mastra applications.
 ---
 
 import YouTube from "@/components/youtube";
+import { Tabs, Tab } from "@/components/tabs";
 
-# Local Development Environment
+# Playground
 
-Mastra provides a local development environment where you can test your agents, workflows, and tools while developing locally.
+Mastra provides a local development environment where you can test your agents, workflows, and tools during development.
 
-<YouTube id="spGlcTEjuXY" />
+Start the local development server by running:
 
-## Launch Development Server
+<Tabs items={["npm", "Mastra CLI"]}>
+  <Tab>
+    ```bash copy
+    npm run dev
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    mastra dev
+    ```
+  </Tab>
+</Tabs>
 
-You can launch the Mastra development environment using the Mastra CLI by running:
+The local development server provides access to the following interfaces:
 
-```bash
-mastra dev
-```
+- Playground: [http://localhost:4111/](http://localhost:4111/)
+- Mastra API: [http://localhost:4111/api](http://localhost:4111/api)
+- OpenAPI Spec: [http://localhost:4111/openapi.json](http://localhost:4111/openapi.json)
+- Swagger UI – API explorer: [http://localhost:4111/swagger-ui](http://localhost:4111/swagger-ui)
 
-By default, the server runs on localhost at http://localhost:4111. Custom port and host can be configured via the
-mastra server config.
+## Local Development Playground
 
-```typescript
-import { Mastra } from "@mastra/core";
+The Playground lets you interact with your agents, workflows, and tools. It provides dedicated interfaces for testing each component of your Mastra application during development and is available at: [http://localhost:4111/](http://localhost:4111/).
 
-export const mastra = new Mastra({
-  server: {
-    port: "4111",
-    host: "0.0.0.0",
-  },
-});
-```
+<YouTube id="spGlcTEjuXY" startTime={126}/>
+
+### Agents
+
+Quickly test and debug your agents during development using the interactive chat interface in the Agent Playground.
+
+![Agents Playground](/image/local-dev/local-dev-agents-playground.jpg)
+
+Key features:
+
+- **Chat Interface**: Talk to your agent and see how it responds in real time.
+- **Model Settings**: Tweak settings like temperature and top-p to see how they affect output.
+- **Agent Endpoints**: See the available REST API routes your agent exposes and how to use them.
+- **Agent Traces**: Step through what the agent did behind the scenes, tool calls, decisions, and more.
+- **Agent Evals**: Run tests against your agent and see how well it performs.
+
+### Workflows
 
-## Dev Playground
+Validate workflows by supplying defined inputs and visualizing each step within the Workflow Playground.
 
-`mastra dev` serves a playground UI for interacting with your agents, workflows, and tools. The playground provides dedicated interfaces for testing each component of your Mastra application during development.
+![Workflows Playground](/image/local-dev/local-dev-workflow-playground.jpg)
 
-### Agent Playground
+Key features:
 
-The Agent playground provides an interactive chat interface where you can test and debug your agents during development. Key features include:
+- **Workflow Visualization**: See your workflow as a visual graph so you can follow the steps and branches at a glance.
+- **Step Inputs & Outputs**: Check the data going into and coming out of each step to see how everything flows.
+- **Run Workflows**: Test your workflow with real inputs to validate the logic and debug any issues.
+- **Execution JSON**: Get the full picture of a run as raw JSON—inputs, outputs, errors, and results included.
+- **Workflow Traces**: Dig into a detailed breakdown of each step, including data flow, tool calls, and any errors along the way.
 
-- **Chat Interface**: Directly interact with your agents to test their responses and behavior.
-- **Prompt CMS**: Experiment with different system instructions for your agent:
-  - A/B test different prompt versions.
-  - Track performance metrics for each variant.
-  - Select and deploy the most effective prompt version.
-- **Agent Traces**: View detailed execution traces to understand how your agent processes requests, including:
-  - Prompt construction.
-  - Tool usage.
-  - Decision-making steps.
-  - Response generation.
-- **Agent Evals**: When you've set up [Agent evaluation metrics](/docs/evals/overview), you can:
-  - Run evaluations directly from the playground.
-  - View evaluation results and metrics.
-  - Compare agent performance across different test cases.
+### Tools
 
-### Workflow Playground
+Quickly test and debug custom tools in isolation using the Tools Playground, without running a full agent or workflow.
 
-The Workflow playground helps you visualize and test your workflow implementations:
+![Tools Playground](/image/local-dev/local-dev-tools-playground.jpg)
 
-- **Workflow Visualization**: Workflow graph visualization.
+Key features:
 
-- **Run Workflows**:
+- **Test Tools in Isolation**: Try out individual tools on their own without running a full agent or workflow.
+- **Input & Responses**: Send sample inputs to see how the tool responds.
+- **Tool Usage**: Find out which agents rely on this tool and how they’re using it.
 
-  - Trigger test workflow runs with custom input data.
-  - Debug workflow logic and conditions.
-  - Simulate different execution paths.
-  - View detailed execution logs for each step.
 
-- **Workflow Traces**: Examine detailed execution traces that show:
-  - Step-by-step workflow progression.
-  - State transitions and data flow.
-  - Tool invocations and their results.
-  - Decision points and branching logic.
-  - Error handling and recovery paths.
+### MCP Servers
 
-### Tools Playground
+Explore connection details, tool usage, and IDE configuration for local MCP server development.
 
-The Tools playground allows you to test your custom tools in isolation:
+![MCP Servers Playground](/image/local-dev/local-dev-mcp-server-playground.jpg)
+
+Key features:
+
+- **Connection Details**: Access the endpoints and config needed to wire up your MCP environment.
+- **Available Tools**:  See all tools currently published, including their names, versions, and which agents use them.
+- **IDE Configuration**: Grab ready-to-use config you can drop into your local setup for testing and publishing tools.
 
-- Test individual tools without running a full agent or workflow.
-- Input test data and view tool responses.
-- Debug tool implementation and error handling.
-- Verify tool input/output schemas.
-- Monitor tool performance and execution time.
 
 ## REST API Endpoints
 
-`mastra dev` also spins up REST API routes for your agents and workflows via the local [Mastra Server](/docs/deployment/server). This allows you to test your API endpoints before deployment. See [Mastra Dev reference](/reference/cli/dev#routes) for more details about all endpoints.
+The local development server exposes a set of REST API routes via the [Mastra Server](/docs/deployment/server), allowing you to test and interact with your agents and workflows before deployment.
 
-You can then leverage the [Mastra Client](/docs/deployment/client) SDK to interact with your served REST API routes seamlessly.
+For a full overview of available API routes, including agents, tools, and workflows, see the [Routes reference](/reference/cli/dev#routes).
 
 ## OpenAPI Specification
 
-`mastra dev` provides an OpenAPI spec at http://localhost:4111/openapi.json
+The local development server includes an OpenAPI specification available at: [http://localhost:4111/openapi.json](http://localhost:4111/openapi.json).
 
-To enable OpenAPI documentation in your Mastra instance, add the following configuration:
+To include OpenAPI documentation in your production server, enable it in the Mastra instance:
 
-```typescript
-import { Mastra } from "@mastra/core";
+```typescript {7} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
 
 export const mastra = new Mastra({
+  // ...
   server: {
     build: {
-      openAPIDocs: true, // Enable OpenAPI documentation
-      // ... other build config options
-    },
+      openAPIDocs: true
+    }
   },
 });
 ```
 
 ## Swagger UI
 
-Swagger UI provides an interactive interface for testing your API endpoints at `mastra dev` provides an OpenAPI spec at http://localhost:4111/swagger-ui.
-To enable Swagger UI in your Mastra instance, add the following configuration:
+The local development server includes an interactive Swagger UI - API explorer available at: [http://localhost:4111/swagger-ui](http://localhost:4111/swagger-ui).
+
+To include Swagger UI in your production server, enable it in the Mastra instance:
 
-```typescript
-import { Mastra } from "@mastra/core";
+```typescript {7} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
 
 export const mastra = new Mastra({
+  // ...
   server: {
     build: {
-      openAPIDocs: true, // Enable OpenAPI documentation
-      swaggerUI: true, // Enable Swagger UI
-      // ... other build config options
+      swaggerUI: true
     },
   },
 });
 ```
 
-## Local Dev Architecture
-
-The local development server is designed to run without any external dependencies or containerization. This is achieved through:
-
-- **Dev Server**: Uses [Hono](https://hono.dev) as the underlying framework to power the [Mastra Server](/docs/deployment/server).
-
-- **In-Memory Storage**: Uses [LibSQL](https://libsql.org/) memory adapters for:
+## Architecture
 
-  - Agent memory management.
-  - Trace storage.
-  - Evals storage.
-  - Workflow snapshots.
+The local development server runs fully self-contained without external dependencies or containers. It leverages:
 
-- **Vector Storage**: Uses [FastEmbed](https://github.com/qdrant/fastembed) for:
-  - Default embedding generation.
-  - Vector storage and retrieval.
-  - Semantic search capabilities.
+- **Dev Server** powered by [Hono](https://hono.dev) for the core [Mastra Server](/docs/deployment/server).
+- **In-Memory Storage** via [LibSQL](https://libsql.org/) adapters for agent memory, traces, evals, and workflow snapshots.
+- **Vector Storage** using [FastEmbed](https://github.com/qdrant/fastembed) for embeddings, vector search, and semantic retrieval.
 
-This architecture allows you to start developing immediately without setting up databases or vector stores, while still maintaining production-like behavior in your local environment.
+This setup lets you start developing immediately with production-like behavior, no database or vector store setup required.
 
-### Model settings
+## Configuration
 
-The local development server also lets you configure the model settings in Overview > Model Settings.
+By default, the server runs on port `4111`. You can customize the host and port through the Mastra server configuration.
 
-You can configure the following settings:
+```typescript {6,7} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
 
-- **Temperature**: Controls randomness in model outputs. Higher values (0-2) produce more creative responses while lower values make outputs more focused and deterministic.
-- **Top P**: Sets cumulative probability threshold for token sampling. Lower values (0-1) make outputs more focused by considering only the most likely tokens.
-- **Top K**: Limits the number of tokens considered for each generation step. Lower values produce more focused outputs by sampling from fewer options.
-- **Frequency Penalty**: Reduces repetition by penalizing tokens based on their frequency in previous text. Higher values (0-2) discourage reuse of common tokens.
-- **Presence Penalty**: Reduces repetition by penalizing tokens that appear in previous text. Higher values (0-2) encourage the model to discuss new topics.
-- **Max Tokens**: Maximum number of tokens allowed in the model's response. Higher values allow for longer outputs but may increase latency.
-- **Max Steps**: Maximum number of steps a workflow or agent can execute before stopping. Prevents infinite loops and runaway processes.
-- **Max Retries**: Number of times to retry failed API calls or model requests before giving up. Helps handle temporary failures gracefully.
+export const mastra = new Mastra({
+  // ...
+  server: {
+    port: 8080,
+    host: "0.0.0.0",
+  },
+});
+```
 
-## Summary
 
-`mastra dev` makes it easy to develop, debug, and iterate on your AI logic in a self-contained environment before deploying to production.
+## Next steps
 
-- [Mastra Dev reference](../../reference/cli/dev.mdx)
+- [Mastra Cloud](/docs/mastra-cloud/overview)
+- [Deployment Overview](/docs/deployment/overview)
+- [Mastra Client SDK](/docs/client-js/overview)

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)