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

package/.docs/guides/deployment/mastra-platform.md

@@ -0,0 +1,70 @@
+# Deploy to 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.
+
+> **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.
+
+## Before you begin
+
+You'll need a [Mastra application](https://mastra.ai/guides/getting-started/quickstart) and a [Mastra platform](https://projects.mastra.ai) account.
+
+> **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.
+
+## Installation
+
+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
+```
+
+## Deploy
+
+1. Deploy your project:
+
+   ```bash
+   mastra server deploy
+   ```
+
+   If you're not already authenticated, the CLI will prompt you to log in. It'll store your credentials locally and any subsequent CLI commands will use these credentials.
+
+   The command runs `mastra build`, uploads the artifact, builds a Docker image, and deploys it to Railway. On first deploy, the CLI creates a `.mastra-project.json` file linking your local project to the platform. Commit this file so subsequent deploys and CI/CD target the same project.
+
+   > **Note:** Environment variables from `.env`, `.env.local`, and `.env.production` are included automatically. On the first deploy, these seed the project if no env vars are set yet. After that, manage env vars through the web dashboard. Review and sanitize these files before first deploy to avoid uploading development-only or personal secrets.
+
+   See the [CLI reference](https://mastra.ai/reference/cli/mastra) for the full list of flags and CI/CD usage.
+
+2. 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.
+
+## Deploy lifecycle
+
+A deploy transitions through **queued → uploading → building → deploying → running** (or **failed**, **cancelled**, **crashed**, or **stopped**). Only one build runs per project at a time. If multiple deploys queue up, only the latest proceeds and the rest are cancelled. Builds running longer than 15 minutes are automatically failed. The first deploy provisions Railway infrastructure and seeds environment variables from your local `.env`. Your server URL remains stable across deploys.
+
+## Related
+
+- [CLI reference](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)

package/.docs/guides/migrations/mastra-cloud.md

@@ -0,0 +1,247 @@
+# Migrate from Mastra Cloud to Mastra platform
+
+The Mastra platform replaces Mastra Cloud with separate Studio and Server products, CLI-driven deploys, and a new observability system. This guide walks you through each step.
+
+## What changed
+
+| Area                 | Mastra Cloud                                   | Mastra platform                                                |
+| -------------------- | ---------------------------------------------- | -------------------------------------------------------------- |
+| **Products**         | Single project                                 | Separate Studio and Server                                     |
+| **Deploys**          | Auto-deploy on push                            | CLI-driven (`mastra studio deploy`, `mastra server deploy`)    |
+| **Project creation** | GitHub import                                  | CLI creates projects on first deploy                           |
+| **Storage**          | Managed LibSQL (Cloud Store) or bring your own | Bring your own hosted database                                 |
+| **Observability**    | Logger-based                                   | `Observability` class with exporters                           |
+| **Env vars**         | Set during project setup                       | Seeded from `.env` on first deploy, managed in dashboard after |
+| **URLs**             | Single URL                                     | Separate Studio and Server URLs                                |
+
+## Before you start
+
+1. Install or update the CLI:
+
+   **npm**:
+
+   ```bash
+   npm install -g mastra@latest
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add -g mastra@latest
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn global add mastra@latest
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add --global mastra@latest
+   ```
+
+2. Authenticate:
+
+   ```bash
+   mastra auth login
+   ```
+
+3. Verify your project builds locally:
+
+   ```bash
+   mastra build
+   ```
+
+## Replace Mastra Cloud Store with a hosted database
+
+Mastra Cloud provided a managed LibSQL database. The Mastra platform does not host a database for you, so you need to point your storage at an externally hosted instance.
+
+If you were already using a hosted database ("bring your own"), no changes are needed. Make sure the connection string is set as an environment variable in the dashboard rather than hardcoded.
+
+If you were using `file:./mastra.db` with Cloud Store, please [contact support](mailto:support@mastra.ai) for a migration path to export and import your data.
+
+## Update observability configuration
+
+Mastra Cloud used logger-based tracing. The Mastra platform uses the `Observability` class with explicit exporters.
+
+Install the observability package:
+
+**npm**:
+
+```bash
+npm install @mastra/observability
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/observability
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/observability
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/observability
+```
+
+**Before (Mastra Cloud):**
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+import { PinoLogger } from '@mastra/loggers'
+
+export const mastra = new Mastra({
+  logger: new PinoLogger({ name: 'my-app', level: 'info' }),
+  // traces appear in Cloud dashboard automatically
+})
+```
+
+**After (Mastra platform):**
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'my-app',
+        exporters: [new DefaultExporter(), new CloudExporter()],
+        spanOutputProcessors: [new SensitiveDataFilter()],
+      },
+    },
+  }),
+})
+```
+
+- `DefaultExporter` persists traces to your storage backend for [Studio](https://mastra.ai/docs/studio/observability).
+- `CloudExporter` sends traces to the Mastra platform when `MASTRA_CLOUD_ACCESS_TOKEN` is set.
+- `SensitiveDataFilter` redacts passwords, tokens, and keys from span data before export.
+
+See the [observability overview](https://mastra.ai/docs/observability/overview) for the full configuration, including composite storage with DuckDB for metrics.
+
+## Deploy Studio
+
+Deploy your hosted Studio instance:
+
+```bash
+mastra studio deploy
+```
+
+The CLI builds your project, uploads the artifact, and deploys it. On first deploy, a `.mastra-project.json` file is created to link your local project to the platform. Commit this file to your repository.
+
+See [Studio deployment](https://mastra.ai/docs/studio/deployment) for details.
+
+## Deploy Server (optional)
+
+If you need a production API endpoint, deploy a Server:
+
+```bash
+mastra server deploy
+```
+
+This creates a separate deployment with a stable API URL, environment variable management, and custom domain support. See the [Server deployment guide](https://mastra.ai/guides/deployment/mastra-platform) for the full walkthrough.
+
+> **Note:** Environment variables from `.env`, `.env.local`, and `.env.production` are included automatically on first deploy. After that, manage env vars through the [web dashboard](https://projects.mastra.ai). Review and sanitize these files before first deploy to avoid uploading development-only or personal secrets.
+
+## Set up CI (optional)
+
+Mastra Cloud auto-deployed on push. The Mastra platform uses CLI-driven deploys, which you can run from any CI provider.
+
+### Prerequisites
+
+1. Create an API token:
+
+   ```bash
+   mastra auth tokens create ci-deploy
+   ```
+
+2. Store the token as a GitHub Actions secret (e.g. `MASTRA_API_TOKEN`).
+
+3. Commit `.mastra-project.json` to your repo (generated on your first manual deploy).
+
+When `MASTRA_API_TOKEN` is set, the CLI runs in headless mode and skips all interactive prompts.
+
+### Deploy Server on push to main
+
+Server deploy accepts org and project from `.mastra-project.json`, so no extra env vars are needed beyond the token:
+
+```yaml
+name: Deploy to Mastra Server
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - run: pnpm install
+      - run: pnpm mastra server deploy --yes --config .mastra-project.json
+        env:
+          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}
+```
+
+### Deploy Studio on push to main
+
+Studio deploy requires `MASTRA_ORG_ID` and `MASTRA_PROJECT_ID` as env vars in headless mode, even when `--config` is provided:
+
+```yaml
+name: Deploy to Mastra Studio
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - run: pnpm install
+      - run: pnpm mastra studio deploy --yes --config .mastra-project.json
+        env:
+          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}
+          MASTRA_ORG_ID: ${{ secrets.MASTRA_ORG_ID }}
+          MASTRA_PROJECT_ID: ${{ secrets.MASTRA_PROJECT_ID }}
+```
+
+## Decommission old Cloud project
+
+Update any clients pointing to your old Mastra Cloud URL to the new Server or Studio URL. Verify traces appear in the new platform by checking the [Studio observability dashboard](https://mastra.ai/docs/studio/observability). Delete your old Mastra Cloud project once everything is confirmed working.
+
+## Related
+
+- [Observability overview](https://mastra.ai/docs/observability/overview)
+- [Studio deployment](https://mastra.ai/docs/studio/deployment)
+- [Server deployment](https://mastra.ai/guides/deployment/mastra-platform)
+- [CLI reference](https://mastra.ai/reference/cli/mastra)
+- [Mastra platform overview](https://mastra.ai/docs/mastra-platform/overview)

package/.docs/guides/migrations/upgrade-to-v1/tracing.md

@@ -46,7 +46,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

package/.docs/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3589 models from 99 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3592 models from 99 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/ollama-cloud.md

@@ -1,6 +1,6 @@
 # ![Ollama Cloud logo](https://models.dev/logos/ollama-cloud.svg)Ollama Cloud
 
-Access 35 Ollama Cloud models through Mastra's model router. Authentication is handled automatically using the `OLLAMA_API_KEY` environment variable.
+Access 36 Ollama Cloud models through Mastra's model router. Authentication is handled automatically using the `OLLAMA_API_KEY` environment variable.
 
 Learn more in the [Ollama Cloud documentation](https://docs.ollama.com/cloud).
 
@@ -43,6 +43,7 @@ for await (const chunk of stream) {
 | `ollama-cloud/gemma3:12b`             | 131K    |       |           |       |       |       | —          | —           |
 | `ollama-cloud/gemma3:27b`             | 131K    |       |           |       |       |       | —          | —           |
 | `ollama-cloud/gemma3:4b`              | 131K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/gemma4:31b`             | 262K    |       |           |       |       |       | —          | —           |
 | `ollama-cloud/glm-4.6`                | 203K    |       |           |       |       |       | —          | —           |
 | `ollama-cloud/glm-4.7`                | 203K    |       |           |       |       |       | —          | —           |
 | `ollama-cloud/glm-5`                  | 203K    |       |           |       |       |       | —          | —           |

package/.docs/models/providers/synthetic.md

@@ -1,6 +1,6 @@
 # ![Synthetic logo](https://models.dev/logos/synthetic.svg)Synthetic
 
-Access 29 Synthetic models through Mastra's model router. Authentication is handled automatically using the `SYNTHETIC_API_KEY` environment variable.
+Access 31 Synthetic models through Mastra's model router. Authentication is handled automatically using the `SYNTHETIC_API_KEY` environment variable.
 
 Learn more in the [Synthetic documentation](https://synthetic.new/pricing).
 
@@ -54,6 +54,7 @@ for await (const chunk of stream) {
 | `synthetic/hf:moonshotai/Kimi-K2-Thinking`                       | 262K    |       |           |       |       |       | $0.55      | $2          |
 | `synthetic/hf:moonshotai/Kimi-K2.5`                              | 262K    |       |           |       |       |       | $0.55      | $2          |
 | `synthetic/hf:nvidia/Kimi-K2.5-NVFP4`                            | 262K    |       |           |       |       |       | $0.55      | $2          |
+| `synthetic/hf:nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4`    | 262K    |       |           |       |       |       | $0.30      | $1          |
 | `synthetic/hf:openai/gpt-oss-120b`                               | 128K    |       |           |       |       |       | $0.10      | $0.10       |
 | `synthetic/hf:Qwen/Qwen2.5-Coder-32B-Instruct`                   | 33K     |       |           |       |       |       | $0.80      | $0.80       |
 | `synthetic/hf:Qwen/Qwen3-235B-A22B-Instruct-2507`                | 256K    |       |           |       |       |       | $0.20      | $0.60       |
@@ -63,6 +64,7 @@ for await (const chunk of stream) {
 | `synthetic/hf:zai-org/GLM-4.6`                                   | 200K    |       |           |       |       |       | $0.55      | $2          |
 | `synthetic/hf:zai-org/GLM-4.7`                                   | 200K    |       |           |       |       |       | $0.55      | $2          |
 | `synthetic/hf:zai-org/GLM-4.7-Flash`                             | 197K    |       |           |       |       |       | $0.06      | $0.40       |
+| `synthetic/hf:zai-org/GLM-5`                                     | 197K    |       |           |       |       |       | $1         | $3          |
 
 ## Advanced configuration
 
@@ -92,7 +94,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "synthetic/hf:zai-org/GLM-4.7-Flash"
+      ? "synthetic/hf:zai-org/GLM-5"
       : "synthetic/hf:MiniMaxAI/MiniMax-M2";
   }
 });

package/.docs/reference/cli/mastra.md

@@ -179,6 +179,10 @@ The port of the Mastra API server to connect to. Defaults to `4111`.
 
 The protocol of the Mastra API server to connect to. Defaults to `http`.
 
+#### `--server-api-prefix`
+
+The API route prefix of the Mastra API server. Defaults to `/api`.
+
 #### `--request-context-presets`
 
 Path to a JSON file containing named [request context](https://mastra.ai/docs/server/request-context) presets. Works the same as the [`mastra dev` flag](#--request-context-presets).
@@ -187,6 +191,142 @@ Path to a JSON file containing named [request context](https://mastra.ai/docs/se
 mastra studio --request-context-presets ./presets.json
 ```
 
+## `mastra studio deploy`
+
+Builds and deploys your project to Mastra platform. Requires authentication via [`mastra auth login`](#mastra-auth-login) or a `MASTRA_API_TOKEN` environment variable.
+
+```bash
+mastra studio deploy
+```
+
+The command runs `mastra build`, zips the output, reads environment variables from `.env`, `.env.local`, and `.env.production`, and uploads everything to the platform. After uploading, it polls the deploy status and streams build logs until the deploy reaches a terminal state.
+
+Organization and project are resolved in order from: Environment variable flag, `.mastra-project.json` config file, current org from credentials, and lastly interactive prompt. On first deploy, the CLI saves the resolved IDs to `.mastra-project.json` so subsequent deploys skip the prompts.
+
+### Arguments
+
+#### `[dir]`
+
+Project directory. Defaults to the current directory.
+
+### Flags
+
+#### `--org`
+
+Organization ID. Can also be set via the `MASTRA_ORG_ID` environment variable.
+
+#### `--project`
+
+Project ID. Can also be set via the `MASTRA_PROJECT_ID` environment variable.
+
+#### `-y, --yes`
+
+Auto-accept defaults without confirmation prompts.
+
+#### `-c, --config`
+
+Path to the project config file. Defaults to `.mastra-project.json`.
+
+#### `--skip-build`
+
+Skip the build step and deploy the existing `.mastra/output` directory.
+
+### CI/CD usage
+
+Set `MASTRA_API_TOKEN`, `MASTRA_ORG_ID`, and `MASTRA_PROJECT_ID` as environment variables for headless deploys. Interactive prompts are skipped automatically when `MASTRA_API_TOKEN` is set.
+
+### `mastra studio deploy list`
+
+Lists all projects with their latest deploy status and URL.
+
+### `mastra studio deploy status`
+
+Shows the status of a specific deploy.
+
+```bash
+mastra studio deploy status <deploy-id>
+```
+
+#### `--watch, -w`
+
+Poll for status changes until the deploy reaches a terminal state.
+
+### `mastra studio deploy logs`
+
+Shows logs for a specific deploy.
+
+```bash
+mastra studio deploy logs <deploy-id>
+```
+
+#### `--follow, -f`
+
+Stream logs in real time.
+
+#### `--tail`
+
+Number of recent log lines to show.
+
+### `mastra studio projects`
+
+Lists all projects in the current organization.
+
+### `mastra studio projects create`
+
+Creates a new project through an interactive prompt.
+
+## `mastra server deploy`
+
+Builds and deploys your project to Server on Mastra platform. Works the same as [`mastra studio deploy`](#mastra-studio-deploy) with the same flags, arguments, and resolution logic.
+
+```bash
+mastra server deploy [dir]
+```
+
+## `mastra auth`
+
+Manages authentication for Mastra platform. Credentials are stored in `~/.mastra/credentials.json`. You can also set the `MASTRA_API_TOKEN` environment variable as an alternative to interactive login.
+
+### `mastra auth login`
+
+Opens a browser for login and stores the credentials locally.
+
+### `mastra auth logout`
+
+Removes stored credentials. If `MASTRA_API_TOKEN` is still set in the environment, the CLI warns that it will continue to be used.
+
+### `mastra auth whoami`
+
+Shows the current user email, user ID, and active organization.
+
+### `mastra auth orgs`
+
+Lists all organizations with your role in each. The current organization is marked.
+
+#### `mastra auth orgs switch`
+
+Switches the active organization through an interactive prompt. Cannot be used when `MASTRA_API_TOKEN` or `MASTRA_ORG_ID` environment variables are set.
+
+### `mastra auth tokens`
+
+Lists all API tokens with their last-used date.
+
+#### `mastra auth tokens create`
+
+Creates a new API token. The secret is displayed once and cannot be retrieved again.
+
+```bash
+mastra auth tokens create <name>
+```
+
+#### `mastra auth tokens revoke`
+
+Revokes an API token.
+
+```bash
+mastra auth tokens revoke <token-id>
+```
+
 ## `mastra lint`
 
 The `mastra lint` command validates the structure and code of your Mastra project to ensure it follows best practices and is error-free.

package/.docs/reference/client-js/agents.md

@@ -445,20 +445,6 @@ console.log(result.success) // true
 
 Both `Agent` (code-defined) and `StoredAgent` instances have methods for managing configuration versions. See the [Editor overview](https://mastra.ai/docs/editor/overview) for an introduction to version management.
 
-### Server endpoints
-
-Version management is also available through the stored agents REST API:
-
-| Method   | Endpoint                                                     | Description                             |
-| -------- | ------------------------------------------------------------ | --------------------------------------- |
-| `GET`    | `/stored/agents/:agentId/versions`                           | List all versions.                      |
-| `POST`   | `/stored/agents/:agentId/versions`                           | Create a new version.                   |
-| `GET`    | `/stored/agents/:agentId/versions/:versionId`                | Get a specific version.                 |
-| `POST`   | `/stored/agents/:agentId/versions/:versionId/activate`       | Set the active version.                 |
-| `POST`   | `/stored/agents/:agentId/versions/:versionId/restore`        | Restore a version (creates a new copy). |
-| `DELETE` | `/stored/agents/:agentId/versions/:versionId`                | Delete a version.                       |
-| `GET`    | `/stored/agents/:agentId/versions/compare?from=<id>&to=<id>` | Compare two versions.                   |
-
 ### Getting an agent with a specific version
 
 Pass a version identifier when getting an agent:

package/.docs/reference/configuration.md

@@ -442,7 +442,7 @@ const mastra = new Mastra({
 
 When `mastra build` is run, Mastra bundles your project into the `.mastra/output` directory. This option controls which packages are excluded from the bundle (marked as "external") and installed separately through a package manager. This is useful when the internal Mastra bundler ([Rollup](https://rollupjs.org/configuration-options/#external)) has trouble bundling certain packages.
 
-By default, `mastra build` sets this option to `true`. If you deploy your project to [Mastra Cloud](https://mastra.ai/docs/mastra-cloud/overview), it also sets this option to `true`.
+By default, `mastra build` sets this option to `true`.
 
 Here's an overview of what the different values mean:
 

package/.docs/reference/index.md

@@ -140,6 +140,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.update()](https://mastra.ai/reference/datasets/update)
 - [.updateItem()](https://mastra.ai/reference/datasets/updateItem)
 - [Harness Class](https://mastra.ai/reference/harness/harness-class)
+- [API Reference](https://mastra.ai/reference/mastra-platform/api)
 - [Cloned Thread Utilities](https://mastra.ai/reference/memory/clone-utilities)
 - [Memory Class](https://mastra.ai/reference/memory/memory-class)
 - [Observational Memory](https://mastra.ai/reference/memory/observational-memory)

package/.docs/reference/logging/pino-logger.md

@@ -2,8 +2,6 @@
 
 A Logger instance is created using `new PinoLogger()` and provides methods to record events at various severity levels.
 
-When deploying to Mastra Cloud, logs are displayed 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.
-
 ## Usage example
 
 ```typescript