@mastra/mcp-docs-server 1.1.24 → 1.1.25-alpha.1

package/.docs/docs/deployment/cloud-providers.md

@@ -2,7 +2,11 @@
 
 Mastra applications can be deployed to cloud providers and serverless platforms. Mastra includes optional built-in deployers for Vercel, Netlify, and Cloudflare to automate the deployment process.
 
-## Supported cloud providers
+## Mastra platform
+
+Mastra provides a platform to deploy your server to the cloud. Read the [Mastra platform deployment guide](https://mastra.ai/guides/deployment/mastra-platform) to learn more.
+
+## Cloud providers
 
 The following guides show how to deploy Mastra to specific cloud providers:
 

package/.docs/docs/deployment/overview.md

@@ -1,6 +1,6 @@
 # Deployment overview
 
-Mastra applications can be deployed to any Node.js-compatible environment. You can deploy a Mastra server, integrate with an existing web framework, deploy to cloud providers, or use Mastra Cloud for managed hosting.
+Mastra applications can be deployed to any Node.js-compatible environment. You can deploy a Mastra server, integrate with an existing web framework, deploy to cloud providers, or use [Mastra platform](https://mastra.ai/docs/mastra-platform/overview) for Studio and server deployment.
 
 ## Runtime support
 
@@ -13,7 +13,7 @@ Mastra can run against any of these runtime environments:
 
 ## Deployment options
 
-### Mastra Server
+### Mastra server
 
 Mastra provides a [server](https://mastra.ai/docs/server/mastra-server) powered by Hono that can be deployed independently. Use the `mastra build` command to build your application and deploy the output to your preferred VM, container, or PaaS platform.
 
@@ -25,6 +25,15 @@ Deploy a Mastra server as part of a monorepo setup, following the same approach
 
 Read about [monorepo deployment](https://mastra.ai/docs/deployment/monorepo).
 
+### Mastra platform
+
+The [Mastra platform](https://mastra.ai/docs/mastra-platform/overview) provides two products for deploying and managing AI applications built with the Mastra framework:
+
+- **Studio**: A hosted visual environment for testing agents, running workflows, and inspecting traces
+- **Server**: A production deployment target that runs your Mastra application as an API server
+
+Learn more in the [Studio deployment guide](https://mastra.ai/docs/studio/deployment) and [Server deployment guide](https://mastra.ai/guides/deployment/mastra-platform).
+
 ### Cloud Providers
 
 Mastra applications can be deployed to cloud providers and serverless platforms. Mastra includes optional built-in deployers for Vercel, Netlify, and Cloudflare to automate the build and deployment process.
@@ -49,12 +58,6 @@ Use these guides when adding Mastra to an existing Next.js or Astro application.
 - [With Astro on Vercel](https://mastra.ai/docs/deployment/web-framework)
 - [With Astro on Netlify](https://mastra.ai/docs/deployment/web-framework)
 
-### Mastra Cloud
-
-We're building Mastra Cloud to be the easiest place to deploy and observe your Mastra agents. It's currently in beta.
-
-Learn more in the [Mastra Cloud docs](https://mastra.ai/docs/mastra-cloud/overview).
-
 ## Workflow runners
 
 Mastra workflows run using the built-in execution engine by default. For production workloads requiring managed infrastructure, workflows can also be deployed to specialized platforms like [Inngest](https://www.inngest.com) that provide step memoization, automatic retries, and real-time monitoring.

package/.docs/docs/index.md

@@ -4,7 +4,7 @@ Build AI agents your users actually depend on. Mastra is a TypeScript framework
 
 ## Quickstart
 
-Run this command to create a new project you can test immediately in [Studio](https://mastra.ai/docs/studio/overview):
+Run this command to create a new project:
 
 **npm**:
 
@@ -30,7 +30,7 @@ yarn create mastra
 bunx create-mastra
 ```
 
-See the [quickstart guide](https://mastra.ai/guides/getting-started/quickstart) for a full walkthrough.
+You can open [Studio](https://mastra.ai/docs/studio/overview) immediately, which is an interactive UI for your Mastra project. See the [quickstart guide](https://mastra.ai/guides/getting-started/quickstart) for a full walkthrough.
 
 ## Integrate with your framework
 

package/.docs/docs/mastra-platform/configuration.md

@@ -0,0 +1,36 @@
+# Configuration
+
+When you deploy to the Mastra platform, the CLI generates a `.mastra-project.json` config file and reads environment variables from your local `.env` files.
+
+This page explains both mechanisms and how they differ between Studio and Server deployments.
+
+## Project config
+
+The `.mastra-project.json` file is auto-generated on your first Studio or Server deploy. It links your local project to a platform project.
+
+Commit it to your version control so that subsequent deploys (including from CI) target the correct project.
+
+Your file will look something like this:
+
+```json
+{
+  "projectId": "06daaac4-89b1-40f0-9e3f-0993e039a627",
+  "projectName": "my-project",
+  "organizationId": "org_01KNA5YSP52SX4M6YVSXC2MAHP"
+}
+```
+
+| Field          | Description                                                                                          |
+| -------------- | ---------------------------------------------------------------------------------------------------- |
+| projectId      | UUID for the project. Assigned when the project is created.                                          |
+| projectName    | Human-readable project name. Used as a display label in the dashboard and CLI output.                |
+| organizationId | The organization that owns the project. All deploys, API keys, and resources are scoped to this org. |
+
+## Environment variables
+
+The CLI reads from `.env` and `.env.local` files in your project directory during deploy. Variables from `.env.local` override those in `.env`.
+
+You can set environment variables like so:
+
+- **Studio**: Environment variables are read from your local `.env` files and bundled into the deploy artifact. To update them, redeploy.
+- **Server**: On the first deploy, the CLI automatically seeds environment variables from your local `.env` files. After that, manage them per-project through the dashboard or API.

package/.docs/docs/mastra-platform/overview.md

@@ -0,0 +1,76 @@
+# Mastra platform
+
+The Mastra platform provides two products for deploying and managing AI applications built with the Mastra framework:
+
+- **Studio**: A hosted visual environment for testing agents, running workflows, and inspecting traces
+- **Server**: A production deployment target that runs your Mastra application as an API server
+
+## Quickstart
+
+Before you begin, ensure you have Node.js 22.13.0 or later installed.
+
+1. Follow the [get started guide](https://mastra.ai/docs) to create your first Mastra project.
+
+2. Install the `mastra` CLI globally:
+
+   **npm**:
+
+   ```bash
+   npm install -g mastra
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add -g mastra
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn global add mastra
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add --global mastra
+   ```
+
+3. Deploy Studio with a single command:
+
+   ```bash
+   mastra studio deploy
+   ```
+
+   On a successful deploy, the CLI will output the URL of your deployed Studio instance.
+
+4. Deploy Server with a single command:
+
+   ```bash
+   mastra server deploy
+   ```
+
+   On a successful deploy, the CLI will output the URL of your deployed Server instance.
+
+You have now successfully deployed both Studio and Server instances of your Mastra application. The CLI created a `.mastra-project.json` file in your project directory.
+
+This file links your local project to a platform project. It's auto-generated on your first deploy and contains the `projectId`, `projectName`, and `organizationId`. Commit this file to your repository so CI/CD knows which project to deploy to.
+
+## Key Concepts
+
+**Projects** are the shared parent entity across all products. A single project can have a Studio deployment and a Server deployment. Projects belong to an **Organization**, which is the multi-tenant container for your team.
+
+Your Mastra application is built from three building blocks:
+
+- [Agents](https://mastra.ai/docs/agents/overview): AI agents that can use tools, follow instructions, and maintain context
+- [Tools](https://mastra.ai/docs/agents/using-tools): Callable functions and integrations available to your agents
+- [Workflows](https://mastra.ai/docs/workflows/overview): Multi-step orchestration pipelines that coordinate agents and tools
+
+## Going to production
+
+Develop your project locally with [`mastra dev`](https://mastra.ai/reference/cli/mastra) and open [Studio](https://mastra.ai/docs/studio/overview) to test your agents, workflows, and tools in a visual environment.
+
+Once you're ready to deploy your application to production, use [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra) and [`mastra server deploy`](https://mastra.ai/reference/cli/mastra) to push your application to the cloud.
+
+Follow the [Studio deployment guide](https://mastra.ai/docs/studio/deployment) and [Server deployment guide](https://mastra.ai/guides/deployment/mastra-platform) for step-by-step instructions.

package/.docs/docs/memory/storage.md

@@ -118,8 +118,6 @@ export const agent = new Agent({
 })
 ```
 
-> **Warning:** Agent-level storage isn't supported when using [Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation doesn't apply if you bring your own database.
-
 ## Threads and resources
 
 Mastra organizes conversations using two identifiers:

package/.docs/docs/observability/logging.md

@@ -2,7 +2,7 @@
 
 Mastra's logging system captures function execution, input data, and output responses in a structured format.
 
-When deploying to Mastra Cloud, logs are shown on the [Logs](https://mastra.ai/docs/mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
+When deploying to the Mastra platform, logs are shown in the dashboard. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
 ## Configuring logs with `PinoLogger`
 

package/.docs/docs/observability/overview.md

@@ -83,7 +83,7 @@ export const mastra = new Mastra({
         serviceName: 'mastra',
         exporters: [
           new DefaultExporter(), // Persists traces to storage for Mastra Studio
-          new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
+          new CloudExporter(), // Sends observability data to Mastra platform (if MASTRA_CLOUD_ACCESS_TOKEN is set)
         ],
         spanOutputProcessors: [
           new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys

package/.docs/docs/observability/tracing/exporters/cloud.md

@@ -1,32 +1,85 @@
 # Cloud exporter
 
-The `CloudExporter` sends traces to Mastra Cloud for centralized monitoring and team collaboration. It's automatically enabled when using the default observability configuration with a valid access token.
+The `CloudExporter` sends traces, logs, metrics, scores, and feedback to the Mastra platform. Use it to route observability data from any Mastra app to a hosted project in the Mastra platform.
 
-## Configuration
+## Quickstart
 
-### Prerequisites
+To connect `CloudExporter`, create an access token, find the destination `projectId`, and add the exporter to your observability config.
 
-1. **Mastra Cloud Account**: Sign up at [cloud.mastra.ai](https://cloud.mastra.ai)
-2. **Mastra Cloud Project**: Create a project in Mastra Cloud. Traces are scoped per project, so even if you only want observability, you need a project to act as the destination for your traces.
-3. **Authentication**: Use either a project-scoped access token or an organization API key. Generate both from Mastra Cloud.
-4. **Environment Variables**: Set your credentials:
+### 1. Create an access token
+
+Run the following command:
+
+```bash
+mastra auth tokens create exporter-token
+```
+
+This command prints a token secret that you can use as `MASTRA_CLOUD_ACCESS_TOKEN`.
+
+If you already have a Mastra Cloud access token, copy the **Observability** value from Mastra Cloud instead. You can find it in either of these places:
+
+- On the **Projects** page, open the project list and find the **Observability** row on the project card.
+- On the project **Overview** page, find the **Observability** row directly below the deployment URL.
+
+Set the token as an environment variable:
 
 ```bash
-MASTRA_CLOUD_ACCESS_TOKEN=mst_xxxxxxxxxxxxxxxx
+MASTRA_CLOUD_ACCESS_TOKEN=<your-cloud-access-token>
 ```
 
-If you authenticate with an organization API key, also set the destination project ID:
+### 2. Find your `projectId`
+
+Run the following command:
 
 ```bash
-MASTRA_CLOUD_ACCESS_TOKEN=sk_xxxxxxxxxxxxxxxx
-MASTRA_PROJECT_ID=project_123
+mastra studio deploy list
+```
+
+The output looks similar to this:
+
+```text
+✅ <your-project-name> (<your-project-id>)
+   Latest:   00000000-0000-0000-0000-000000000000 — running
+   URL:      https://260407.studio.mastra.cloud
 ```
 
-### Basic Setup
+In this output, the value in parentheses is the `projectId`:
 
-Project-scoped access tokens work without any extra routing configuration:
+```text
+<your-project-id>
+```
+
+Set it as an environment variable:
 
-```typescript
+```bash
+MASTRA_PROJECT_ID=<your-project-id>
+```
+
+### 3. Set your environment variables
+
+Tokens created with `mastra auth tokens create` are organization-scoped, so `MASTRA_PROJECT_ID` is required.
+
+If you use a project-scoped token from Mastra Cloud instead, `CloudExporter` can route without `projectId`, but setting it explicitly is still supported.
+
+Add both values to your environment:
+
+```bash
+MASTRA_CLOUD_ACCESS_TOKEN=<your-cloud-access-token>
+MASTRA_PROJECT_ID=<your-project-id>
+```
+
+For example:
+
+```bash
+MASTRA_CLOUD_ACCESS_TOKEN=<your-cloud-access-token>
+MASTRA_PROJECT_ID=<your-project-id>
+```
+
+### 4. Enable `CloudExporter`
+
+The following example demonstrates how to add `CloudExporter` to your observability config:
+
+```ts
 import { Mastra } from '@mastra/core'
 import { Observability, CloudExporter } from '@mastra/observability'
 
@@ -36,7 +89,10 @@ export const mastra = new Mastra({
       production: {
         serviceName: 'my-service',
         exporters: [
-          new CloudExporter(), // Uses MASTRA_CLOUD_ACCESS_TOKEN env var
+          new CloudExporter({
+            accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
+            projectId: process.env.MASTRA_PROJECT_ID,
+          }),
         ],
       },
     },
@@ -44,24 +100,45 @@ export const mastra = new Mastra({
 })
 ```
 
-### Organization API keys
+Set `serviceName` in code on the observability config, not on `CloudExporter` itself. In the example above, the value is `configs.production.serviceName`.
 
-Organization API keys are scoped to the whole org, so the exporter needs a project ID (letters, numbers, hyphens, underscores only) to generate project-scoped collector routes.
+For example:
 
-```typescript
-new CloudExporter({
-  accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
-  projectId: process.env.MASTRA_PROJECT_ID,
+```ts
+import { Mastra } from '@mastra/core'
+import { Observability, CloudExporter } from '@mastra/observability'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      production: {
+        serviceName: 'api-server',
+        exporters: [new CloudExporter()],
+      },
+    },
+  }),
 })
 ```
 
-When `projectId` is set, base endpoints resolve to `/projects/:projectId/ai/{signal}/publish`. Without it, the exporter keeps using `/ai/{signal}/publish`.
+Use a stable `serviceName` value. In Studio, traces can be filtered by **Deployments → Service Name**, so a consistent name makes traces easier to find.
+
+Visit [Observability configuration reference](https://mastra.ai/reference/observability/tracing/configuration) for the full observability config shape.
+
+If you prefer, rely entirely on environment variables:
+
+```ts
+new CloudExporter()
+```
+
+With `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` set, `CloudExporter` automatically sends data to the correct Mastra Cloud project.
 
-### Recommended Configuration
+> **Note:** Visit [CloudExporter reference](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter) for the full list of configuration options.
 
-Include CloudExporter in your observability configuration:
+## Recommended configuration
 
-```typescript
+Include `DefaultExporter` if you also want to inspect local traces in Studio or persist observability data to your configured storage.
+
+```ts
 import { Mastra } from '@mastra/core'
 import {
   Observability,
@@ -75,10 +152,7 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'mastra',
-        exporters: [
-          new DefaultExporter(),
-          new CloudExporter(), // Sends traces to Mastra Cloud (requires MASTRA_CLOUD_ACCESS_TOKEN)
-        ],
+        exporters: [new DefaultExporter(), new CloudExporter()],
         spanOutputProcessors: [new SensitiveDataFilter()],
       },
     },
@@ -86,68 +160,47 @@ export const mastra = new Mastra({
 })
 ```
 
-### Complete Configuration
+## Complete configuration
+
+The following example demonstrates how to configure custom endpoints and batching behavior:
 
-```typescript
+```ts
 new CloudExporter({
-  // Optional - defaults to env var
   accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
-
-  // Optional - required for organization API keys or any project-scoped collector route
-  // Letters, numbers, hyphens, and underscores only
   projectId: process.env.MASTRA_PROJECT_ID,
-
-  // Optional - for self-hosted Mastra Cloud
   endpoint: 'https://cloud.your-domain.com',
-
-  // Batching configuration
-  maxBatchSize: 1000, // Max spans per batch
-  maxBatchWaitMs: 5000, // Max wait before sending batch
-
-  // Diagnostic logging
-  logLevel: 'info', // debug | info | warn | error
+  maxBatchSize: 1000,
+  maxBatchWaitMs: 5000,
+  logLevel: 'info',
 })
 ```
 
-## Viewing traces
-
-### Mastra Cloud Dashboard
-
-1. Navigate to [cloud.mastra.ai](https://cloud.mastra.ai)
-
-2. Select the project associated with your access token
-
-3. Go to **Observability → Traces**
-
-4. Use filters to find specific traces:
+## Viewing data in Mastra Cloud
 
-   - Service name
-   - Time range
-   - Trace ID
-   - Error status
+After you enable `CloudExporter`, open your project in [Mastra Cloud](https://cloud.mastra.ai) to inspect the exported data.
 
-> **Note:** If you use a project-scoped token, view the project that issued the token. If you use an organization API key, view the project named in `MASTRA_PROJECT_ID` or `projectId`.
+- Open your project and select **Open Studio**.
+- In Studio, go to **Traces** to inspect agent and workflow traces.
+- Open the filter menu and use **Deployments → Service Name** to isolate traces from a specific app or deployment.
+- Use the **Logs** page in the project dashboard to inspect exported logs.
+- Use the project named by `MASTRA_PROJECT_ID` when you work with organization-scoped tokens.
 
-### Features
+> **Note:** If you use a project-scoped token, open the project that issued the token. If you use an organization-scoped token, open the project named by `MASTRA_PROJECT_ID`.
 
-- **Trace Timeline** - Visual execution flow
-- **Span Details** - Inputs, outputs, metadata
-- **Performance Metrics** - Latency, token usage
-- **Team Collaboration** - Share trace links
+When you deploy with Mastra Cloud, set **Deployment → Service Name** to a stable value and keep it aligned with the `serviceName` in your observability config. This makes traces easier to filter in Studio through **Deployments → Service Name** when multiple services or deployments send data to the same project.
 
 ## Performance
 
-> **Info:** CloudExporter uses intelligent batching to optimize network usage. Traces are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
+> **Info:** CloudExporter uses batching to optimize network usage. Events are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
 
-### Batching Behavior
+### Batching behavior
 
-- Traces are batched up to `maxBatchSize` (default: 1000)
-- Batches are sent when full or after `maxBatchWaitMs` (default: 5 seconds)
-- Failed batches are retried with exponential backoff
-- Graceful degradation if Mastra Cloud is unreachable
+- Events are batched up to `maxBatchSize` (default: 1000).
+- Batches are sent when full or after `maxBatchWaitMs` (default: 5 seconds).
+- Failed batches are retried with exponential backoff.
+- The exporter degrades gracefully if Mastra Cloud is unreachable.
 
 ## Related
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [DefaultExporter](https://mastra.ai/docs/observability/tracing/exporters/default)
-- [Mastra Cloud Documentation](https://mastra.ai/docs/mastra-cloud/overview)
+- [DefaultExporter](https://mastra.ai/docs/observability/tracing/exporters/default)

package/.docs/docs/observability/tracing/exporters/default.md

@@ -59,7 +59,7 @@ export const mastra = new Mastra({
         serviceName: 'mastra',
         exporters: [
           new DefaultExporter(), // Persists traces to storage for Studio
-          new CloudExporter(), // Sends traces to Mastra Cloud (requires MASTRA_CLOUD_ACCESS_TOKEN)
+          new CloudExporter(), // Sends observability data to Mastra platform (requires MASTRA_CLOUD_ACCESS_TOKEN)
         ],
         spanOutputProcessors: [new SensitiveDataFilter()],
       },

package/.docs/docs/observability/tracing/overview.md

@@ -32,7 +32,7 @@ export const mastra = new Mastra({
         serviceName: 'mastra',
         exporters: [
           new DefaultExporter(), // Persists traces to storage for Studio
-          new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
+          new CloudExporter(), // Sends observability data to Mastra platform (if MASTRA_CLOUD_ACCESS_TOKEN is set)
         ],
         spanOutputProcessors: [
           new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
@@ -56,7 +56,7 @@ This configuration includes:
 - **Exporters**:
 
   - `DefaultExporter` - Persists traces to your configured storage for Studio
-  - `CloudExporter` - Sends traces to Mastra Cloud (requires `MASTRA_CLOUD_ACCESS_TOKEN`)
+  - `CloudExporter` - Sends observability data to Mastra platform (requires `MASTRA_CLOUD_ACCESS_TOKEN`)
 
 - **Span Output Processors**: `SensitiveDataFilter` - Redacts sensitive fields
 
@@ -69,7 +69,7 @@ Exporters determine where your trace data is sent and how it's stored. They inte
 Mastra provides two built-in exporters:
 
 - **[Default](https://mastra.ai/docs/observability/tracing/exporters/default)** - Persists traces to local storage for viewing in Studio
-- **[Cloud](https://mastra.ai/docs/observability/tracing/exporters/cloud)** - Sends traces to Mastra Cloud for production monitoring and collaboration
+- **[Cloud](https://mastra.ai/docs/observability/tracing/exporters/cloud)** - Sends observability data to Mastra platform for production monitoring and collaboration
 
 ### External Exporters
 

package/.docs/docs/studio/deployment.md

@@ -4,8 +4,8 @@ Studio is a React-based Single Page Application (SPA) that runs in the browser a
 
 You can deploy Studio in two primary ways:
 
-- [Cloud](https://mastra.ai/docs/mastra-cloud/overview) hosts Studio for you and allows you to share access with your team via link
-- You can self-host Studio on your own infrastructure, either alongside your Mastra server or separately as a standalone SPA
+- The Mastra platform provides a hosted Studio for you and allows you to share access with your team via link
+- Self-host Studio on your own infrastructure, either alongside your Mastra server or separately as a standalone SPA
 
 On this page you'll learn how to deploy Studio on your own infrastructure. As the finer details of deployment can vary widely based on your needs and setup, we'll cover the general principles and options available to you.
 
@@ -49,15 +49,33 @@ mastra studio
 
 Open [localhost:3000](http://localhost:3000) in your browser to see the Studio UI. By default, it will attempt to connect to a Mastra server running at `http://localhost:4111`. If it doesn't find one there, you'll see a form where you can enter your Mastra instance URL and API prefix.
 
-If you're hosting Studio under a subpath (for example `/agents` behind Nginx), set `MASTRA_STUDIO_BASE_PATH` before starting Studio:
+The command uses Node's built-in `http` module and [`serve-handler`](https://www.npmjs.com/package/serve-handler) to serve the static files.
+
+> **Note:** If you're hosting Studio under a subpath (for example `/agents` behind Nginx), set `MASTRA_STUDIO_BASE_PATH` before starting Studio:
+>
+> ```bash
+> MASTRA_STUDIO_BASE_PATH=/agents mastra studio
+> ```
+>
+> This updates the HTML base URL and static asset routing so the standalone Studio works correctly under that subpath.
+
+## Mastra platform
+
+The [Mastra platform](https://mastra.ai/docs/mastra-platform/overview) allows you to deploy your Studio to the cloud. Run a single CLI command, and the platform handles provisioning, deployment, and hosting.
+
+Run the following command:
 
 ```bash
-MASTRA_STUDIO_BASE_PATH=/agents mastra studio
+mastra studio deploy
 ```
 
-This updates the HTML base URL and static asset routing so the standalone Studio works correctly under that subpath.
+> **Note:** See the [CLI reference](https://mastra.ai/reference/cli/mastra) for the full list of flags and CI/CD usage.
 
-The command uses Node's built-in `http` module and [`serve-handler`](https://www.npmjs.com/package/serve-handler) to serve the static files.
+This builds your project (compiling `src/mastra/` into `.mastra/output`), packages it as an artifact ZIP, uploads it, and deploys it to a cloud sandbox.
+
+If this is your first deploy, the CLI will prompt you to create a new project or select an existing one. The `.mastra-project.json` file is written automatically.
+
+A deploy transitions through **queued → uploading → starting → running** (or **failed** if something goes wrong). If a sandbox is already running for your project, the platform hot-updates it in place with no downtime. Otherwise it creates a fresh sandbox. Your instance URL is assigned per project slug and remains stable across deploys. Environment variables from `.env`, `.env.local`, and `.env.production` are included automatically.
 
 ## Running a server
 

package/.docs/docs/studio/observability.md

@@ -87,7 +87,7 @@ export const mastra = new Mastra({
         serviceName: 'mastra',
         exporters: [
           new DefaultExporter(), // Persists traces to storage for Mastra Studio
-          new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
+          new CloudExporter(), // Sends observability data to Mastra platform (if MASTRA_CLOUD_ACCESS_TOKEN is set)
         ],
         spanOutputProcessors: [
           new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys

package/.docs/docs/studio/overview.md

@@ -1,8 +1,6 @@
 # Studio
 
-Studio provides an interactive UI for building, testing, and managing your agents, workflows, and tools. Run it locally during development, or [deploy it](https://mastra.ai/docs/studio/deployment) to production so your team can manage agents, monitor performance, and gain insights through built-in observability.
-
-Add [authentication](https://mastra.ai/docs/studio/auth) to protect your deployed Studio with login screens, role-based access control, and permission-based UI rendering so you can control what each team member can see and do. You can also [create a project in Mastra Cloud](https://mastra.ai/docs/mastra-cloud/setup) for a hosted option.
+Studio provides an interactive UI for building, testing, and managing your agents, workflows, and tools. Run it locally during development, add [authentication](https://mastra.ai/docs/studio/auth), or [deploy it](https://mastra.ai/docs/studio/deployment) to production so your team can manage agents, monitor performance, and gain insights through built-in observability.
 
 [YouTube video player](https://www.youtube-nocookie.com/embed/ojGu6Bi4wYk)
 
@@ -39,7 +37,7 @@ Once the server is running, you can:
 - Open the Studio UI at [http://localhost:4111](http://localhost:4111/) to interact with your agents, workflows, and tools.
 - Visit <http://localhost:4111/swagger-ui> to discover and interact with the underlying REST API.
 
-To run Studio in production, see [Studio deployment](https://mastra.ai/docs/studio/deployment). To run Studio independently from your Mastra server, use [`mastra studio`](https://mastra.ai/reference/cli/mastra).
+While Studio is running, you can edit your [agents](https://mastra.ai/docs/agents/overview), [workflows](https://mastra.ai/docs/workflows/overview), and other parts of your Mastra application in real time.
 
 ## Primitives