@mastra/mcp-docs-server 1.1.35 → 1.1.36-alpha.1

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

@@ -4,7 +4,7 @@ Mastra applications can be deployed to cloud providers and serverless platforms.
 
 ## 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.
+Mastra provides a platform to deploy your server to the cloud. Read the [Mastra platform deployment guide](https://mastra.ai/docs/mastra-platform/overview) to learn more.
 
 ## 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 platform](https://mastra.ai/docs/mastra-platform/overview) for Studio and server deployment.
+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 observability, Studio, and server deployment.
 
 ## Runtime support
 
@@ -27,12 +27,13 @@ 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:
+The [Mastra platform](https://mastra.ai/docs/mastra-platform/overview) provides three products for deploying, monitoring, 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
+- [**Observability**](https://mastra.ai/docs/mastra-platform/observability): A standalone hosted product for searchable traces, logs, and metrics across Mastra projects and deploys
+- [**Studio**](https://mastra.ai/docs/mastra-platform/studio): A hosted visual environment for testing agents, running workflows, and inspecting traces
+- [**Server**](https://mastra.ai/docs/mastra-platform/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).
+Learn more in the [Mastra platform overview](https://mastra.ai/docs/mastra-platform/overview).
 
 ### Cloud Providers
 

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

@@ -41,18 +41,34 @@ To pin the deploy to a specific env file (instead of relying on the default sele
 mastra studio deploy --env-file .env.production --yes
 ```
 
+### Observability
+
+The following environment variables configure the Observability product on the Mastra platform.
+
+| Variable                                 | Description                                                                                                                                                                                   |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MASTRA_PLATFORM_ACCESS_TOKEN`           | Org-scoped access token. The CLI writes this during observability provisioning and uses it for platform authentication.                                                                       |
+| `MASTRA_PROJECT_ID`                      | UUID of the platform project. `MastraPlatformExporter` uses it to link observability data to the platform project. Studio and Server deploys read the project ID from `.mastra-project.json`. |
+| `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` | Optional observability endpoint override. This is only set automatically for local platform development. Defaults to `https://observability.mastra.ai`.                                       |
+| `MASTRA_ORG_ID`                          | Overrides the active organization for CLI commands. You can also set it with the `--org` flag on supported commands.                                                                          |
+
+`MastraPlatformExporter` reads `MASTRA_PLATFORM_ACCESS_TOKEN` to authenticate platform export.
+
 ## Multiple environments
 
-A platform project maps to a single deployed instance with one set of env vars. There is no built-in concept of `staging` vs `production` slots within a project. To run the same codebase across multiple environments, create one project per environment and override `.mastra-project.json` per deploy.
+A platform project maps to a single deployed instance with one set of env vars. Platform projects don't have built-in `staging` vs `production` slots. To run the same codebase across multiple environments, create one project per environment and use the matching `.mastra-project.json` file for each deploy.
 
 ```bash
-# Create-and-deploy each environment (first time only)
+# Create and deploy each environment for the first time.
 mastra studio deploy --project "my-app-staging" --env-file .env.staging --yes
 mastra studio deploy --project "my-app-production" --env-file .env.production --yes
 
-# Subsequent deploys — set MASTRA_PROJECT_ID per environment
-MASTRA_PROJECT_ID="<staging-id>" mastra studio deploy --env-file .env.staging --yes
-MASTRA_PROJECT_ID="<production-id>" mastra studio deploy --env-file .env.production --yes
+# For subsequent deploys, restore the matching .mastra-project.json file before deploying.
+cp .mastra-project.staging.json .mastra-project.json
+mastra studio deploy --env-file .env.staging --yes
+
+cp .mastra-project.production.json .mastra-project.json
+mastra studio deploy --env-file .env.production --yes
 ```
 
-Each project has its own Studio URL and its own observability data. When using [`MastraPlatformExporter`](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform), set `MASTRA_PROJECT_ID` and `MASTRA_CLOUD_ACCESS_TOKEN` per environment so traces route to the matching Studio project.
+Each project has its own Studio URL and can send observability data to the Mastra platform. When using [`MastraPlatformExporter`](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform), set `MASTRA_PROJECT_ID` and `MASTRA_PLATFORM_ACCESS_TOKEN` per environment so traces route to the matching platform project.

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

@@ -0,0 +1,99 @@
+# Observability on Mastra platform
+
+Observability on Mastra platform is a standalone hosted product for searchable traces, logs, and metrics across Mastra projects and deploys. Use it when you want observability without deploying Studio first or setting up local storage.
+
+Mastra can configure platform observability during project setup. The CLI provisions a platform project, writes the required environment variables, and registers observability exporters in your Mastra config.
+
+## Quickstart
+
+Choose the setup path that matches your project. New and existing projects can use the CLI to provision Observability automatically, while manual setup is available when you already manage platform projects and environment variables yourself.
+
+### New project
+
+Create a new Mastra project:
+
+**npm**:
+
+```bash
+npm create mastra@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm create mastra
+```
+
+**Yarn**:
+
+```bash
+yarn create mastra
+```
+
+**Bun**:
+
+```bash
+bunx create-mastra
+```
+
+When prompted, enable Mastra Observability:
+
+```bash
+Enable Mastra Observability? (will open auth flow)
+
+> Yes
+```
+
+The CLI authenticates with Mastra platform, creates a platform project, writes the required environment variables, and configures the observability exporters.
+
+### Existing non-Mastra projects
+
+If you already have an application, such as a Next.js app, but have not added Mastra yet, run `mastra init` and enable Mastra Observability when prompted:
+
+**npm**:
+
+```bash
+npx mastra init
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra init
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra init
+```
+
+**Bun**:
+
+```bash
+bun x mastra init
+```
+
+The CLI can select an existing platform project or create a new one.
+
+### Manual setup
+
+Create a project in [Mastra Platform](https://projects.mastra.ai), add `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` to `.env`, then register `MastraPlatformExporter` in your Mastra config. Add `MastraStorageExporter` if you also want to persist observability events to your configured Mastra Storage:
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+import { Observability, MastraPlatformExporter } from '@mastra/observability'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [new MastraPlatformExporter()],
+      },
+    },
+  }),
+})
+```
+
+See [Mastra platform configuration](https://mastra.ai/docs/mastra-platform/configuration) for the environment variables used by platform observability.

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

@@ -1,65 +1,22 @@
 # Mastra platform
 
-The [Mastra platform](https://projects.mastra.ai) provides two products for deploying and managing AI applications built with the Mastra framework:
+The [Mastra platform](https://projects.mastra.ai) provides three products for deploying, monitoring, 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
+- [**Observability**](https://mastra.ai/docs/mastra-platform/observability): The baseline product for every platform project, with searchable traces, logs, and metrics across Mastra projects and deploys
+- [**Studio**](https://mastra.ai/docs/mastra-platform/studio): A hosted visual environment for testing agents, running workflows, and inspecting traces. Starting with Studio also gives you Observability.
+- [**Server**](https://mastra.ai/docs/mastra-platform/server): A production deployment target that runs your Mastra application as an API server. Starting with Server also gives you Observability.
 
-## Quickstart
+## Get started
 
-Before you begin, ensure you have Node.js 22.13.0 or later installed.
+Choose the path that matches what you want to do:
 
-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.
+- **Add hosted observability**: Use [Observability](https://mastra.ai/docs/mastra-platform/observability) to collect searchable traces, logs, and metrics across projects and deploys. Start here if you want monitoring without deploying Studio or Server first.
+- **Deploy Studio**: Use [Studio](https://mastra.ai/docs/mastra-platform/studio) to host the visual development environment for your team. Start here if you want a shared UI for testing agents, running workflows, and inspecting traces.
+- **Deploy Server**: Use [Server](https://mastra.ai/docs/mastra-platform/server) to run your Mastra application as a production API server. Start here when you’re ready to serve agents, tools, and workflows from the cloud.
 
 ## 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.
+**Projects** are the shared parent entity across all products. A single project can have Observability, 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:
 
@@ -73,6 +30,6 @@ Develop your project locally with [`mastra dev`](https://mastra.ai/reference/cli
 
 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.
+Follow the [Studio on Mastra platform](https://mastra.ai/docs/mastra-platform/studio) and [Server on Mastra platform](https://mastra.ai/docs/mastra-platform/server) docs for step-by-step instructions.
 
-If you host your Mastra application on your own infrastructure, you can still send observability data to Studio using the [MastraPlatformExporter](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform).
+If you host your Mastra application on your own infrastructure, you can still send observability data to Mastra platform using the [MastraPlatformExporter](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform).

package/.docs/{guides/deployment/mastra-platform.md → docs/mastra-platform/server.md}

@@ -1,46 +1,42 @@
-# Deploy to Mastra platform
+# Server on Mastra platform
 
-Mastra Server deploys your application as a production API server on cloud infrastructure. You get a stable API endpoint, environment variable management, custom domain support, and deploy history out of the box.
+Server on Mastra platform is a production deployment target that runs your Mastra application as an API server. Use it when you want the platform to build, deploy, host, and manage your Mastra server.
 
-> **Tip:** This guide covers deploying the standalone server generated by `mastra build`. If you need to deploy Studio to the Mastra platform, see [Studio deployment](https://mastra.ai/docs/studio/deployment) instead.
+You get a stable API endpoint, environment variable management, custom domain support, and deploy history out of the box.
 
-## Before you begin
+> **Note:** Server deploy provisions hosted storage automatically. If you override storage with [LibSQLStore](https://mastra.ai/reference/storage/libsql) and a file URL, switch to a remotely hosted database because Mastra platform uses an ephemeral filesystem.
 
-You'll need a [Mastra application](https://mastra.ai/guides/getting-started/quickstart) and a [Mastra platform](https://projects.mastra.ai) account.
+## Quickstart
 
-> **Warning:** Mastra platform uses an ephemeral filesystem, so any storage you configure (including observability storage) must be hosted externally. If you're using [LibSQLStore](https://mastra.ai/reference/storage/libsql) with a file URL, switch to a remotely hosted database.
+1. Follow the [get started guide](https://mastra.ai/docs) to create your first Mastra project.
 
-## Installation
+2. Install the `mastra` CLI globally:
 
-Install the `mastra` CLI globally:
+   **npm**:
 
-**npm**:
-
-```bash
-npm install -g mastra
-```
-
-**pnpm**:
+   ```bash
+   npm install -g mastra
+   ```
 
-```bash
-pnpm add -g mastra
-```
+   **pnpm**:
 
-**Yarn**:
+   ```bash
+   pnpm add -g mastra
+   ```
 
-```bash
-yarn global add mastra
-```
+   **Yarn**:
 
-**Bun**:
+   ```bash
+   yarn global add mastra
+   ```
 
-```bash
-bun add --global mastra
-```
+   **Bun**:
 
-## Deploy
+   ```bash
+   bun add --global mastra
+   ```
 
-1. Deploy your project:
+3. Deploy your project:
 
    ```bash
    mastra server deploy
@@ -54,7 +50,7 @@ bun add --global mastra
 
    See the [CLI reference](https://mastra.ai/reference/cli/mastra) for the full list of flags.
 
-2. Verify your deployment at the URL printed by the CLI. Append `/api/agents` to confirm it returns a JSON list of your agents.
+4. Verify your deployment at the URL printed by the CLI. Append `/api/agents` to confirm it returns a JSON list of your agents.
 
    > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.
 
@@ -181,11 +177,8 @@ The CLI reads `organizationId` and `projectId` from `.mastra-project.json` by de
 
 ## Related
 
-- [CLI reference: `mastra server deploy`](https://mastra.ai/reference/cli/mastra)
-- [CLI reference: `mastra server pause`](https://mastra.ai/reference/cli/mastra)
-- [CLI reference: `mastra server restart`](https://mastra.ai/reference/cli/mastra)
-- [CLI reference: `mastra studio deploy`](https://mastra.ai/reference/cli/mastra)
-- [CLI reference: `mastra auth tokens`](https://mastra.ai/reference/cli/mastra)
-- [Mastra platform overview](https://mastra.ai/docs/mastra-platform/overview)
-- [Studio deployment](https://mastra.ai/docs/studio/deployment)
-- [Deployment overview](https://mastra.ai/docs/deployment/overview)
+- [`mastra server deploy`](https://mastra.ai/reference/cli/mastra)
+- [`mastra server pause`](https://mastra.ai/reference/cli/mastra)
+- [`mastra server restart`](https://mastra.ai/reference/cli/mastra)
+- [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra)
+- [`mastra auth tokens`](https://mastra.ai/reference/cli/mastra)

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

@@ -0,0 +1,81 @@
+# Studio on Mastra platform
+
+Studio on Mastra platform is a hosted visual environment for testing agents, running workflows, and inspecting traces. Use it when you want to share Studio with your team without hosting the Studio UI yourself.
+
+## Quickstart
+
+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 outputs the URL of your deployed Studio instance.
+
+On your first deploy, the CLI prompts you to create a new project or select an existing one. It then creates a `.mastra-project.json` file in your project directory. This file links your local project to a platform project. It contains the `projectId`, `projectName`, and `organizationId`. Commit this file to your repository so CI/CD knows which project to deploy to.
+
+## How deploy works
+
+The `mastra studio deploy` command builds your project, compiles `src/mastra/` into `.mastra/output`, packages the output as an artifact ZIP, uploads it, and deploys it to a cloud sandbox.
+
+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 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.
+
+See the [`mastra studio deploy` CLI reference](https://mastra.ai/reference/cli/mastra) for the full list of flags and CI/CD usage.
+
+## Environment files
+
+The deploy bundles environment variables from a `.env` or `.env.*` file in the project directory. If no env file is present, the deploy errors with `No env file found for deploy.` after the build step. Add at least an empty `.env` file before running the command.
+
+When multiple env files are present, the CLI prompts you to pick one. To select non-interactively, pass `--env-file`:
+
+```bash
+mastra studio deploy --env-file .env.production --yes
+```
+
+This is also how you target multiple environments from a single codebase: maintain one env file per environment, such as `.env.staging` and `.env.production`, and pass the right one to each deploy. Each environment still requires its own Mastra platform project. See [Configuration](https://mastra.ai/docs/mastra-platform/configuration) for the multi-environment pattern.
+
+## Create a new project non-interactively
+
+`mastra studio deploy` can create a project on first run. If `--project <name>` doesn't match an existing project, the CLI uses the value as the new project name and creates it after confirmation. Combined with `--yes`, this is fully scriptable:
+
+```bash
+mastra studio deploy --project "my-new-project" --yes
+```
+
+Use this from CI or AI coding agents instead of `mastra studio projects create`, which is interactive only.
+
+## Self-host Studio
+
+To deploy Studio on your own infrastructure, see [Studio deployment](https://mastra.ai/docs/studio/deployment).
+
+## Related
+
+- [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra)

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

@@ -1,6 +1,6 @@
 # Observability overview
 
-Mastra's observability system gives you visibility into every agent run, workflow step, tool call, and model interaction. It captures three complementary signals that work together to help you understand what your application is doing and why.
+Mastra's observability system gives you visibility into every agent run, workflow step, tool call, and model interaction. Agent behavior depends on model responses, prompts, tools, memory, and workflow state, so observability helps you inspect runtime decisions from day one. It captures three complementary signals that work together to help you understand what your application is doing and why.
 
 - [**Tracing**](https://mastra.ai/docs/observability/tracing/overview): Records every operation as a hierarchical timeline of spans, capturing inputs, outputs, token usage, and timing.
 - [**Logging**](https://mastra.ai/docs/observability/logging): Forwards structured log entries from your application and Mastra internals to observability storage, correlated to traces automatically.
@@ -24,9 +24,9 @@ Logs are correlated to traces automatically. Every `logger.info()`, `logger.warn
 
 All three signals share correlation IDs (trace ID, span ID, entity type, entity name), so you can jump between a metric spike, the traces behind it, and the logs within those traces.
 
-## Get started
+## Quickstart
 
-Install `@mastra/observability` and a storage backend:
+Install `@mastra/observability` and storage backends that support traces and metrics:
 
 **npm**:
 
@@ -83,7 +83,7 @@ export const mastra = new Mastra({
         serviceName: 'mastra',
         exporters: [
           new MastraStorageExporter(), // Persists observability events to Mastra Storage
-          new MastraPlatformExporter(), // Sends observability events to Mastra Platform (if MASTRA_CLOUD_ACCESS_TOKEN is set)
+          new MastraPlatformExporter(), // Sends observability events to Mastra platform (if MASTRA_PLATFORM_ACCESS_TOKEN is set)
         ],
         spanOutputProcessors: [
           new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
@@ -96,6 +96,10 @@ export const mastra = new Mastra({
 
 This enables tracing, log forwarding, and metrics. Mastra also supports external tracing providers like Langfuse, Datadog, and any OpenTelemetry-compatible platform. See [Tracing](https://mastra.ai/docs/observability/tracing/overview) for configuration details.
 
+## Mastra platform
+
+For hosted traces, logs, and metrics across projects and deploys, see [Observability on Mastra platform](https://mastra.ai/docs/mastra-platform/observability).
+
 ## Storage
 
 Not all storage backends support every signal. Traces and logs work with most backends, but metrics require an OLAP-capable store like DuckDB (development) or ClickHouse (production). For the full compatibility list, see [storage provider support](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage).
@@ -108,4 +112,5 @@ For production environments with high traffic, use composite storage to route th
 - [Logging](https://mastra.ai/docs/observability/logging)
 - [Metrics](https://mastra.ai/docs/observability/metrics/overview)
 - [Mastra Studio](https://mastra.ai/docs/studio/observability)
-- [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics)
+- [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics)
+- [Mastra platform observability](https://mastra.ai/docs/mastra-platform/observability)

package/.docs/docs/observability/tracing/exporters/mastra-platform.md

@@ -1,10 +1,10 @@
-# Mastra Platform exporter
+# Mastra platform exporter
 
 The `MastraPlatformExporter` 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.
 
 > **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` class is still exported from `@mastra/observability` for backward compatibility, but it is deprecated. New code should use `MastraPlatformExporter`.
 
-> **Self-hosted or standalone apps:** If you host your Mastra application on your own infrastructure (not on Mastra Platform), you still need a deployed Studio project to view traces, logs, and metrics. `MastraPlatformExporter` sends data to a Studio project, so one must exist before you can use it.
+> **Self-hosted or standalone apps:** If you host your Mastra application on your own infrastructure (not on Mastra platform), you still need a deployed Studio project to view traces, logs, and metrics. `MastraPlatformExporter` sends data to a Studio project, so one must exist before you can use it.
 >
 > 1. [Create a Mastra project](https://mastra.ai/guides/getting-started/quickstart) if you don't have one yet.
 > 2. [Deploy Studio](https://mastra.ai/docs/studio/deployment) to the Mastra platform with `mastra studio deploy`.
@@ -13,8 +13,8 @@ The `MastraPlatformExporter` sends traces, logs, metrics, scores, and feedback t
 ## Version compatibility
 
 - `MastraPlatformExporter` is available starting in `@mastra/observability@1.12.0`. In `1.8.0` through `1.11.x` the same exporter ships only as `CloudExporter`; the constructor signature and environment variables are identical.
-- In `@mastra/observability@1.8.0` through `1.9.1`, set `MASTRA_CLOUD_TRACES_ENDPOINT=https://observability.mastra.ai` in addition to `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID`.
-- Starting in `@mastra/observability@1.9.2`, the exporter defaults to `https://observability.mastra.ai`, so `MASTRA_CLOUD_TRACES_ENDPOINT` is only required when you want to send telemetry to a different collector.
+- In `@mastra/observability@1.8.0` through `1.9.1`, set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai` in addition to `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID`.
+- Starting in `@mastra/observability@1.9.2`, the exporter defaults to `https://observability.mastra.ai`, so `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` is only required when you want to send telemetry to a different collector.
 
 ## Quickstart
 
@@ -28,7 +28,7 @@ Run the following command:
 mastra auth tokens create exporter-token
 ```
 
-This command prints a token secret that you can use as `MASTRA_CLOUD_ACCESS_TOKEN`.
+This command prints a token secret that you can use as `MASTRA_PLATFORM_ACCESS_TOKEN`.
 
 If you already have an access token, copy the **Observability** value from the Mastra platform instead. You can find it in either of these places:
 
@@ -38,7 +38,7 @@ If you already have an access token, copy the **Observability** value from the M
 Set the token as an environment variable:
 
 ```bash
-MASTRA_CLOUD_ACCESS_TOKEN=<your-cloud-access-token>
+MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
 ```
 
 ### 2. Find your `projectId`
@@ -74,20 +74,20 @@ MASTRA_PROJECT_ID=<your-project-id>
 Set both values in your environment so `MastraPlatformExporter` can authenticate and route telemetry to the correct project:
 
 ```bash
-MASTRA_CLOUD_ACCESS_TOKEN=<your-cloud-access-token>
+MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
 MASTRA_PROJECT_ID=<your-project-id>
 ```
 
 If you use `@mastra/observability@1.8.0` through `1.9.1`, also set the Mastra platform collector explicitly:
 
 ```bash
-MASTRA_CLOUD_TRACES_ENDPOINT=https://observability.mastra.ai
+MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai
 ```
 
-If you want to send telemetry somewhere other than Mastra platform, set `MASTRA_CLOUD_TRACES_ENDPOINT` as well. Pass either a base origin or a full traces publish URL ending in `/spans/publish`.
+If you want to send telemetry somewhere other than Mastra platform, set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` as well. Pass either a base origin or a full traces publish URL ending in `/spans/publish`.
 
 ```bash
-MASTRA_CLOUD_TRACES_ENDPOINT=https://collector.example.com
+MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
 ```
 
 When you pass a base origin, `MastraPlatformExporter` derives the matching publish URLs for traces, logs, metrics, scores, and feedback automatically.
@@ -124,7 +124,7 @@ If you prefer, rely entirely on environment variables:
 new MastraPlatformExporter()
 ```
 
-With `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` set, `MastraPlatformExporter` sends data to the Mastra platform project you configured. If you also set `MASTRA_CLOUD_TRACES_ENDPOINT`, it sends data to that collector instead.
+With `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` set, `MastraPlatformExporter` sends data to the Mastra platform project you configured. If you also set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`, it sends data to that collector instead.
 
 > **Note:** Visit [MastraPlatformExporter reference](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for the full list of configuration options.
 
@@ -156,10 +156,10 @@ export const mastra = new Mastra({
 
 ## Complete configuration
 
-`MastraPlatformExporter` defaults to Mastra platform. If you want to send telemetry to a different collector, set `MASTRA_CLOUD_TRACES_ENDPOINT` in your environment or pass `endpoint` in code.
+`MastraPlatformExporter` defaults to Mastra platform. If you want to send telemetry to a different collector, set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` in your environment or pass `endpoint` in code.
 
 ```bash
-MASTRA_CLOUD_TRACES_ENDPOINT=https://collector.example.com
+MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
 ```
 
 The following example demonstrates how to override the collector endpoint and batching behavior in code:

package/.docs/docs/observability/tracing/exporters/mastra-storage.md

@@ -61,7 +61,7 @@ export const mastra = new Mastra({
         serviceName: 'mastra',
         exporters: [
           new MastraStorageExporter(), // Persists observability events to Mastra Storage
-          new MastraPlatformExporter(), // Sends observability events to Mastra Platform (requires MASTRA_CLOUD_ACCESS_TOKEN)
+          new MastraPlatformExporter(), // Sends observability events to Mastra platform (requires MASTRA_PLATFORM_ACCESS_TOKEN)
         ],
         spanOutputProcessors: [new SensitiveDataFilter()],
       },

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

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