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

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/server/middleware.md

@@ -97,22 +97,62 @@ export const mastra = new Mastra({
 
 ### Authorization (User Isolation)
 
-Authentication verifies who the user is. Authorization controls what they can access. Without authorization middleware, an authenticated user could access other users' threads by guessing IDs or manipulating the `resourceId` parameter.
+Authentication verifies who the user is. Authorization controls what they can access. Without resource ID scoping, an authenticated user could access other users' threads by guessing IDs or manipulating the `resourceId` parameter.
 
-Mastra provides reserved context keys that, when set by middleware, take precedence over client-provided values. The server automatically enforces these keys across memory and agent endpoints:
+The simplest way to scope memory and threads to the authenticated user is the `mapUserToResourceId` callback in the auth config:
 
 ```typescript
 import { Mastra } from '@mastra/core'
-import { MASTRA_RESOURCE_ID_KEY } from '@mastra/core/request-context'
-import { getAuthenticatedUser } from '@mastra/server/auth'
 
 export const mastra = new Mastra({
   server: {
     auth: {
       authenticateToken: async token => {
-        // Your auth logic returns the user
-        return verifyToken(token) // { id: 'user-123', ... }
+        return verifyToken(token) // { id: 'user-123', orgId: 'org-456', ... }
       },
+      mapUserToResourceId: user => user.id,
+    },
+  },
+})
+```
+
+After successful authentication, `mapUserToResourceId` is called with the authenticated user object. The returned value is set as `MASTRA_RESOURCE_ID_KEY` on the request context, which works across all server adapters (Hono, Express, Next.js, etc.).
+
+The resource ID doesn't have to be `user.id`. Common patterns:
+
+```typescript
+// Org-scoped
+mapUserToResourceId: user => `${user.orgId}:${user.id}`
+
+// From a JWT claim
+mapUserToResourceId: user => user.tenantId
+
+// Composite key
+mapUserToResourceId: user => `${user.workspaceId}:${user.projectId}:${user.id}`
+```
+
+With a resource ID set, the server automatically:
+
+- **Filters thread listing** to only return threads owned by the user
+- **Validates thread access** and returns 403 if accessing another user's thread
+- **Forces thread creation** to use the authenticated user's ID
+- **Validates message operations** including deletion, ensuring messages belong to owned threads
+
+Even if a client passes `?resourceId=other-user-id`, the auth-set value takes precedence. Attempts to access threads or messages owned by other users will return a 403 error.
+
+#### Advanced: Setting resource ID in middleware
+
+For more complex scenarios (e.g., looking up the resource ID from a database), you can set `MASTRA_RESOURCE_ID_KEY` directly in middleware:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MASTRA_RESOURCE_ID_KEY } from '@mastra/core/request-context'
+import { getAuthenticatedUser } from '@mastra/server/auth'
+
+export const mastra = new Mastra({
+  server: {
+    auth: {
+      authenticateToken: async token => verifyToken(token),
     },
     middleware: [
       {
@@ -134,10 +174,7 @@ export const mastra = new Mastra({
             return c.json({ error: 'Unauthorized' }, 401)
           }
 
-          // Force all API operations to use this user's ID
-          // This takes precedence over any client-provided resourceId
           requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id)
-
           return next()
         },
       },
@@ -148,15 +185,6 @@ export const mastra = new Mastra({
 
 `server.middleware` runs before Mastra's per-route auth checks. When middleware needs the authenticated user, call `getAuthenticatedUser()` to resolve it from the configured auth provider without changing the default route auth flow.
 
-With this middleware, the server automatically:
-
-- **Filters thread listing** to only return threads owned by the user
-- **Validates thread access** and returns 403 if accessing another user's thread
-- **Forces thread creation** to use the authenticated user's ID
-- **Validates message operations** including deletion, ensuring messages belong to owned threads
-
-Even if a client passes `?resourceId=other-user-id`, the middleware-set value takes precedence. Attempts to access threads or messages owned by other users will return a 403 error.
-
 #### Using `MASTRA_THREAD_ID_KEY`
 
 You can also set `MASTRA_THREAD_ID_KEY` to override the client-provided thread ID:

package/.docs/docs/server/request-context.md

@@ -234,7 +234,18 @@ export const weatherTool = createTool({
 
 ## Reserved keys
 
-Mastra reserves special context keys for security purposes. When set by middleware, these keys take precedence over client-provided values. The server automatically validates ownership and returns 403 errors when users attempt to access resources they don't own.
+Mastra reserves special context keys for security purposes. When set, these keys take precedence over client-provided values. The server automatically validates ownership and returns 403 errors when users attempt to access resources they don't own.
+
+The easiest way to set `MASTRA_RESOURCE_ID_KEY` is via the `mapUserToResourceId` callback in auth config:
+
+```typescript
+auth: {
+  authenticateToken: async token => verifyToken(token),
+  mapUserToResourceId: user => user.id,
+}
+```
+
+You can also set these keys manually in middleware:
 
 ```typescript
 import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from '@mastra/core/request-context'