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

package/.docs/docs/agents/a2a.md

@@ -0,0 +1,235 @@
+# A2A (Agent-to-Agent)
+
+Mastra supports the Agent-to-Agent (A2A) protocol for exposing agents as remote agents that other agents and services can discover, call, and track over time. A2A is useful when an agent needs to cross a network boundary without exposing the remote agent's internal tools, memory, prompts, or implementation.
+
+## When to use A2A
+
+- A parent agent should delegate work to a specialized agent owned by another service or team.
+- A remote agent should keep its tools, prompts, memory, workflows, and infrastructure private.
+- A backend, browser app, or another A2A-compatible system needs programmatic access to a Mastra agent.
+- Long-running remote work needs task IDs, status updates, artifacts, cancellation, resubscription, or push notifications.
+
+## How A2A works
+
+A2A maps to the roles described in the [A2A core concepts](https://a2a-protocol.org/latest/topics/key-concepts/):
+
+- **User**: The human, service, or process that asks for work.
+- **Client agent**: The caller that discovers a remote agent, sends messages, and listens for task updates.
+- **Remote agent**: The Mastra agent running behind an A2A endpoint.
+
+Any registered Mastra agent can be called as an A2A remote agent. It keeps using its own instructions, tools, memory, workflows, and server configuration; A2A changes how the agent is reached, not how it's authored.
+
+The flow is:
+
+1. Register a standard Mastra agent in your `Mastra` instance.
+2. Start Mastra Server or mount Mastra routes into your own server.
+3. Mastra exposes the agent through an agent card at `/.well-known/:agentId/agent-card.json` and an execution endpoint at `/a2a/:agentId`.
+4. A client reads the card, sends A2A JSON-RPC methods such as `message/send`, `message/stream`, `tasks/get`, `tasks/cancel`, or `tasks/resubscribe`, then receives task, artifact, and status events.
+
+Agent cards describe the remote agent's name, description, provider, endpoint URL, capabilities, security metadata, and skills. Capabilities advertise features such as streaming and push notifications. Skills describe what the remote agent can do so callers can decide whether it fits the task.
+
+A2A represents work as messages and tasks. Messages carry text, file, or structured data parts. Tasks are stateful units of work with IDs and lifecycle states, so clients can follow long-running work, send follow-up turns, cancel work, or resubscribe after a disconnect. Remote agents can also return artifacts, such as text, files, or structured data, during or after a task.
+
+## Quickstart
+
+Start with any agent registered in your `Mastra` instance. When Mastra Server runs, the agent is available as a remote A2A agent through its registered ID.
+
+For an agent registered as `research-agent`, Mastra exposes:
+
+- Agent card: `/.well-known/research-agent/agent-card.json`
+- Execution endpoint: `/a2a/research-agent`
+
+Use `MastraClient.getA2A()` to fetch the agent card and call the remote agent:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+const client = new MastraClient({
+  baseUrl: 'https://agent.example.com',
+})
+
+const a2a = client.getA2A('research-agent')
+const card = await a2a.getAgentCard()
+
+console.log(card.name, card.capabilities)
+```
+
+## Discover and call remote agents
+
+A2A discovery starts with the agent card. The [A2A discovery guide](https://a2a-protocol.org/latest/topics/agent-discovery/) describes well-known URI discovery, registries, and direct configuration. Mastra supports the well-known route for registered agents at `/.well-known/:agentId/agent-card.json`.
+
+Use `sendMessageStream()` to receive task status and artifact updates over Server-Sent Events (SSE):
+
+```typescript
+const stream = a2a.sendMessageStream({
+  message: {
+    kind: 'message',
+    role: 'user',
+    messageId: crypto.randomUUID(),
+    parts: [{ kind: 'text', text: 'Summarize this incident report.' }],
+  },
+})
+
+for await (const event of stream) {
+  if (event.kind === 'artifact-update') {
+    console.log(event.artifact.parts)
+  }
+}
+```
+
+If a stream disconnects while a task is still running, use `resubscribeTask()` to receive live updates for the in-progress task:
+
+```typescript
+const updates = a2a.resubscribeTask({
+  id: 'task-123',
+})
+
+for await (const event of updates) {
+  console.log(event)
+}
+```
+
+Agent cards can contain sensitive information, such as internal URLs or private skill descriptions. Protect restricted cards with access controls, and use agent card verification when a client needs to validate that a card came from a trusted source.
+
+## Push notifications
+
+Mastra supports A2A push notifications for remote agents that advertise `capabilities.pushNotifications`. Use push notifications when a client can't keep a stream open, or when a long-running task should update a callback URL after the original request ends.
+
+After a client has a task ID, it can register a callback URL for that task:
+
+```typescript
+await a2a.setTaskPushNotificationConfig({
+  taskId: 'task-123',
+  pushNotificationConfig: {
+    url: 'https://app.example.com/a2a/tasks',
+    token: process.env.A2A_WEBHOOK_TOKEN,
+  },
+})
+```
+
+Mastra Server sends the current task snapshot to registered callbacks when the task reaches `completed`, `failed`, `canceled`, or `input-required`. Push notification delivery is best-effort. Protect callback URLs, validate notification tokens, and avoid exposing internal network targets as push notification destinations.
+
+## Sign and verify agent cards
+
+Mastra supports signed A2A agent cards so clients can verify that a discovered card came from a trusted publisher and wasn't changed in transit. Configure signing on the Mastra server that exposes the remote agent:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+
+export const mastra = new Mastra({
+  server: {
+    a2a: {
+      agentCardSigning: {
+        privateKey: process.env.A2A_AGENT_CARD_PRIVATE_KEY!,
+        protectedHeader: {
+          alg: 'ES256',
+          kid: 'agent-card-key',
+        },
+      },
+    },
+  },
+})
+```
+
+When signing is configured, Mastra includes a `signatures` array on the agent card. Client verification is opt-in, and unsigned cards still return unchanged.
+
+Verify a signed card with `MastraClient.getA2A()`:
+
+```typescript
+const card = await a2a.getAgentCard({
+  verifySignature: {
+    algorithms: ['ES256'],
+    keyProvider: async ({ kid, jku }) => {
+      return fetchTrustedPublicJwk({ kid, jku })
+    },
+  },
+})
+```
+
+Use client-side signature verification to enforce trusted keys before calling the remote agent.
+
+## Use remote agents as subagents
+
+Use `A2AAgent` when a Mastra parent agent should call a remote A2A agent as a subagent. Create an `A2AAgent` with a remote agent card URL or single-agent domain, then register it in the parent agent's `agents` map.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { A2AAgent } from '@mastra/core/a2a'
+
+const remoteWeatherAgent = new A2AAgent({
+  url: 'https://weather.example.com',
+})
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'Answer user questions and delegate weather questions when needed.',
+  model: 'openai/gpt-5.4',
+  agents: {
+    remoteWeatherAgent,
+  },
+})
+```
+
+> **Tip:** If `url` points to a domain, `A2AAgent` fetches the agent card from `/.well-known/agent-card.json`. Use this for single-agent servers. For multi-agent servers, pass the explicit card URL, such as `https://agent.example.com/.well-known/:agentId/agent-card.json`. If `url` already ends with `/agent-card.json`, Mastra uses that URL directly. `A2AAgent` doesn't discover agent IDs beyond the URL you provide.
+
+`A2AAgent` implements Mastra's subagent interface. The parent agent can call it like any other subagent, while `A2AAgent` handles the protocol details.
+
+During execution, `A2AAgent`:
+
+- Fetches and caches the remote agent card.
+- Reads the execution URL and capabilities from the card.
+- Calls `message/send` for non-streaming runs or `message/stream` when streaming is supported.
+- Converts remote messages, tasks, artifacts, and status updates into Mastra subagent results.
+- Supports `resumeGenerate()` and `resumeStream()` when the remote task requires follow-up input or resubscription.
+
+If the remote card doesn't advertise streaming support, `A2AAgent.stream()` falls back to the non-streaming generate path and returns a buffered stream result.
+
+## Configure subagent calls
+
+`A2AAgent` accepts request options for authenticated or constrained environments:
+
+```typescript
+import { A2AAgent } from '@mastra/core/a2a'
+
+const remoteWeatherAgent = new A2AAgent({
+  url: 'https://weather.example.com',
+  headers: {
+    Authorization: `Bearer ${process.env.WEATHER_AGENT_TOKEN}`,
+  },
+  retries: 2,
+  backoffMs: 250,
+  maxBackoffMs: 1000,
+  timeoutMs: 30_000,
+})
+```
+
+You can also pass `credentials`, `fetch`, and `abortSignal` when the runtime needs custom fetch behavior or request cancellation.
+
+## Verify subagent cards
+
+Use `verifyAgentCard` when a parent agent should validate a remote agent before delegating work to it. The verification hook receives the fetched agent card and context about where and when it was fetched.
+
+```typescript
+import { A2AAgent } from '@mastra/core/a2a'
+
+const remoteWeatherAgent = new A2AAgent({
+  url: 'https://weather.example.com/.well-known/agent-card.json',
+  verifyAgentCard: {
+    verify: async (card, context) => {
+      if (card.provider?.organization !== 'Weather Inc') {
+        throw new Error(`Unexpected provider for ${context.cardUrl}`)
+      }
+    },
+  },
+})
+```
+
+Use this hook to enforce expected providers, expected endpoints, certificate-bound identities, signed cards, or other trust requirements before a parent agent delegates to the remote agent.
+
+## Related
+
+- [Agent reference](https://mastra.ai/reference/agents/agent)
+- [JavaScript client agents reference](https://mastra.ai/reference/client-js/agents)
+- [A2A core concepts](https://a2a-protocol.org/latest/topics/key-concepts/)
+- [A2A discovery guide](https://a2a-protocol.org/latest/topics/agent-discovery/)

package/.docs/docs/agents/response-caching.md

@@ -1,8 +1,8 @@
-# Response caching
+# Response Caching
 
-Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to drop latency to single-digit milliseconds and avoid paying for repeated calls.
+Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to reduce latency and avoid paying for repeated calls.
 
-Caching is implemented as the [`ResponseCache`](https://mastra.ai/reference/processors/response-cache) input processor. There is no agent-level option — to enable caching, register the processor explicitly. This keeps the API surface small while we collect feedback; per-call overrides flow through `RequestContext`.
+Caching is implemented as the [`ResponseCache`](https://mastra.ai/reference/processors/response-cache) input processor. Mastra doesn't provide an agent-level option. To enable caching, register the processor explicitly. This keeps the API surface small while Mastra collects feedback; per-call overrides flow through `RequestContext`.
 
 ## When to use response caching
 
@@ -51,15 +51,15 @@ await agent.stream('hello', { requestContext: ctx })
 
 Three fields are overridable per call:
 
-- `key` — string or function. Overrides the auto-derived cache key for this request only.
-- `scope` — string or `null`. Overrides the tenant/user scope for this request only. `null` opts out of scoping.
-- `bust` — boolean. Skips the cache read but still writes on completion (useful for "force refresh" buttons).
+- `key`: String or function. Overrides the auto-derived cache key for this request only.
+- `scope`: String or `null`. Overrides the tenant/user scope for this request only. `null` opts out of scoping.
+- `bust`: Boolean. Skips the cache read but still writes on completion (useful for "force refresh" buttons).
 
-`cache`, `ttl`, and `agentId` stay on the constructor — they are instance-level concerns and not safe to vary per call.
+`cache`, `ttl`, and `agentId` stay on the constructor. They're instance-level concerns and not safe to vary per call.
 
 ## Tenant scoping
 
-By default, `ResponseCache` looks up `MASTRA_RESOURCE_ID_KEY` on the request context and uses it as the cache scope. This means an agent that already populates the resource id (e.g. via memory) gets per-user isolation automatically — two users never see each other's cached responses.
+By default, `ResponseCache` looks up `MASTRA_RESOURCE_ID_KEY` on the request context and uses it as the cache scope. This means an agent that already populates the resource id (e.g. via memory) gets per-user isolation automatically. Two users never see each other's cached responses.
 
 Override explicitly when you need a different scope:
 
@@ -75,7 +75,7 @@ new Agent({
 })
 ```
 
-Pass `scope: null` to deliberately share entries across all callers — only use this for known-public, non-personalized content.
+Pass `scope: null` to deliberately share entries across all callers. Only use this for known-public, non-personalized content.
 
 ## Custom cache backend
 
@@ -102,7 +102,7 @@ For a custom backend, extend `MastraServerCache` and implement its abstract meth
 
 `ResponseCache` hooks into `processLLMRequest` (cache lookup, short-circuits on hit) and `processLLMResponse` (cache write on completion). Both run inside the agentic loop _after_ memory has loaded and earlier input processors have transformed the prompt.
 
-This means the cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model — i.e. _after_ memory has loaded and earlier input processors have run — and each step in an agentic tool loop is independently cached.
+This means the cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model. The key is created _after_ memory has loaded and earlier input processors have run, and each step in an agentic tool loop is independently cached.
 
 ## What's in the cache key
 
@@ -137,7 +137,7 @@ If the function throws, the processor falls back to the default key derivation s
 
 When the processor finds a cache hit, it short-circuits the LLM call by returning the cached chunks from `processLLMRequest`. The agentic loop synthesizes a stream from those chunks instead of calling the model. `agent.generate()` collects them into a `FullOutput`; `agent.stream()` returns a `MastraModelOutput` whose chunks come from the cached buffer, so consumers iterating `fullStream` or awaiting `text`, `usage`, and `finishReason` see the cached values.
 
-Cache writes happen after the response completes. Failed runs (errors, tripwire activations) are not cached, so the next call retries cleanly.
+Cache writes happen after the response completes. Failed runs (errors, tripwire activations) aren't cached, so the next call retries cleanly.
 
 ## Related
 

package/.docs/docs/agents/signals.md

@@ -1,6 +1,6 @@
 # Signals
 
-> **Experimental:** Agent signals are experimental. The API may change in a future release.
+> **Experimental:** Agent signals are experimental. Breaking changes may occur without a major version bump until the API is stable.
 
 Signals are a way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send signals. Mastra either wakes the agent when the thread is idle or drops the signal into the running agent loop.
 

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).