@mastra/mcp-docs-server 1.2.8-alpha.2 → 1.2.8-alpha.23

package/.docs/docs/server/auth/fga.md

@@ -254,6 +254,46 @@ class MyFGAProvider implements IFGAProvider {
 }
 ```
 
+## System actors
+
+Autonomous and scheduled agents run without an end user. Mark these calls with an actor signal so FGA can tell them apart from user requests:
+
+- `true` or `{ actorKind: 'system' }` identifies an anonymous system actor.
+- The object form can also carry `agentId`, `permissions`, and `scope` to identify and constrain the acting agent.
+
+By default, a trusted actor skips the user-centric `require()` check after a tenant-scope check. To enforce per-agent least privilege, implement the optional `requireActor` method on your provider. It receives the actor and the same `FGACheckParams` as `require`, and throws `FGADeniedError` to deny. When your provider doesn't implement `requireActor`, the trusted-actor bypass is preserved, so adding it is backward compatible.
+
+```typescript
+import { FGADeniedError } from '@mastra/core/auth/ee'
+import type { ActorSignal, FGACheckParams, IFGAProvider } from '@mastra/core/auth/ee'
+
+class MyFGAProvider implements IFGAProvider {
+  // ...check, require, filterAccessible...
+
+  async requireActor(actor: ActorSignal, params: FGACheckParams): Promise<void> {
+    const agentId = actor === true ? undefined : actor.agentId
+    // Resolve the agent's real grants from a trusted source keyed by agentId.
+    const granted = await this.grantsForAgent(agentId)
+    const required = Array.isArray(params.permission) ? params.permission : [params.permission]
+    if (!required.some(permission => granted.includes(permission))) {
+      throw new FGADeniedError(null, params.resource, params.permission)
+    }
+  }
+}
+```
+
+### Trust requirements
+
+The actor signal is trusted input, so construct it server-side:
+
+- Treat `actor` as a per-call signal. Durable workflows forward it when a run starts, but don't restore the initial actor on resume. Pass it explicitly on every trusted resume, or resolve a fresh actor through agent `defaultOptions`. Without a current actor, user authorization applies and a missing user fails closed.
+- Mastra strips `actor` from execution options handled by its built-in agent HTTP routes. Set it in server-side code, for example a scheduled job or a workflow, never from client input.
+- Establish tenant scope server-side. Built-in agent HTTP routes ignore a client-supplied `organizationId` in the request context, and the trusted-actor path requires an `organizationId` to be set.
+- Durable resume keeps its existing request-context recovery and merge behavior. This doesn't make a persisted actor trusted for a later workflow segment.
+- The tenant-scope check confirms that a trusted `organizationId` exists. It doesn't verify that `actor.agentId` belongs to that organization. When that relationship matters, verify it in `requireActor` using authoritative provider data.
+- Treat `actor.permissions` as a claim, not a grant. A provider that enforces least privilege resolves the agent's authoritative permissions from a trusted source, for example a manifest or your FGA backend keyed by `agentId`, rather than trusting the inline values.
+- Once a provider implements `requireActor`, errors from that method stop execution. Mastra doesn't fall back to organization-only authorization.
+
 ## Related
 
 - [Authentication overview](https://mastra.ai/docs/server/auth)

package/.docs/docs/server/auth/simple-auth.md

@@ -74,9 +74,7 @@ Add custom headers using the `headers` option:
 
 ```typescript
 new SimpleAuth({
-  tokens: {
-    /* ... */
-  },
+  tokens: {/* ... */},
   headers: ['X-API-Key', 'X-Custom-Auth'],
 })
 ```

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

@@ -247,6 +247,8 @@ auth: {
 }
 ```
 
+When the resource ID is derived this way, clients can omit `memory.resource` from agent generate and stream request bodies — the server-derived value is used instead (and always takes precedence over any client-provided value). If a request uses memory and neither the body nor the request context provides a resource ID, the server responds with a 400 error.
+
 You can also set these keys manually in middleware:
 
 ```typescript

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

@@ -91,6 +91,8 @@ See [request context](https://mastra.ai/docs/server/request-context) for configu
 
 ## Evaluation
 
+Use the date filter to limit score metrics to a preset or custom time range.
+
 ### Scorers
 
 The Scorers tab displays the results of your agent's scorers as they run. When messages pass through your agent, the defined scorers evaluate each output asynchronously and render their results here. This allows you to understand how your scorers respond to different interactions, compare performance across test cases, and identify areas for improvement.

package/.docs/docs/workflows/control-flow.md

@@ -591,9 +591,7 @@ const embedStep = createStep({
   inputSchema: z.object({ chunk: z.string() }),
   outputSchema: z.object({ embedding: z.array(z.number()) }),
   execute: async ({ inputData }) => ({
-    embedding: [
-      /* vector embedding */
-    ],
+    embedding: [/* vector embedding */],
   }),
 })
 

package/.docs/docs/workspace/filesystem.md

@@ -23,6 +23,7 @@ Available providers:
 - [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem): Stores files in a directory on disk
 - [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem): Stores files in Amazon S3 or S3-compatible storage (R2, MinIO, Tigris)
 - [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem): Stores files in Google Cloud Storage
+- [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem): Stores files in a Mastra Platform workspace bucket
 - [`GoogleDriveFilesystem`](https://mastra.ai/reference/workspace/google-drive-filesystem): Stores files inside a Google Drive folder
 - [`AzureBlobFilesystem`](https://mastra.ai/reference/workspace/azure-blob-filesystem): Stores files in Azure Blob Storage
 - [`FilesSDKFilesystem`](https://mastra.ai/reference/workspace/files-sdk-filesystem): Stores files in any [FilesSDK](https://files-sdk.dev) adapter (S3, R2, GCS, Azure Blob, Vercel Blob, local filesystem, and more) — useful when you want one provider that can target multiple backends

package/.docs/docs/workspace/sandbox.md

@@ -26,6 +26,7 @@ A sandbox provider executes commands in a controlled environment:
 - [`DaytonaSandbox`](https://mastra.ai/reference/workspace/daytona-sandbox): Executes commands in isolated Daytona cloud sandboxes
 - [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox): Executes commands in isolated E2B cloud sandboxes
 - [`ModalSandbox`](https://mastra.ai/reference/workspace/modal-sandbox): Executes commands in isolated Modal cloud sandboxes
+- [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox): Executes commands in a sandbox tied to a Mastra Platform environment
 - [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox): Executes commands in ephemeral, isolated Railway cloud sandboxes
 
 ## Basic usage

package/.docs/guides/getting-started/quickstart.md

@@ -2,21 +2,21 @@
 
 # Mastra Quickstart
 
-**For AI agents:** This page provides information for humans on how to run an interactive CLI to create a boilerplate Mastra project (with agents, workflows, and tools). You can run it non-interactively like so: `npm create mastra@latest <project-name> -- --default`. If you need to build a Mastra project from scratch (e.g. as a Node.js script printing to stdout), navigate to <https://mastra.ai/docs/getting-started/manual-install> instead.
+**For AI agents:** Create a new Mastra project non-interactively with `npm create mastra@latest <project-name> -- --llm <provider>`, replacing `<provider>` with `openai`, `anthropic`, `google`, or `xai`. For a minimal project without an agent or model provider, use `npm create mastra@latest <project-name> -- --empty`. To build a Mastra project from scratch, see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install).
 
-The `create mastra` CLI command is the quickest way to get started. It walks you through setup and creates example agents, workflows, and tools for you to run locally or adapt.
+The `create-mastra` CLI is the quickest way to start a Mastra project. It creates an agent harness with workspace tools, memory, task tracking, web access, schedules, storage, and observability.
 
-If you need more control over the setup, see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install). You can also use [`mastra init`](https://mastra.ai/reference/cli/mastra) for existing projects.
+For more control, see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install). To add Mastra to an existing project, use [`mastra init`](https://mastra.ai/reference/cli/mastra).
 
-> **📹 Watch:** Watch [Mastra AI agent course](https://www.youtube.com/watch?v=lCmf_qrGfGA) for a guided introduction to building agents with Mastra.
+> **📹 Watch:** Watch the [Mastra AI agent course](https://www.youtube.com/watch?v=lCmf_qrGfGA) for a guided introduction to building agents with Mastra.
 
 ## Before you begin
 
-- You'll need an API key from a supported [model provider](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/openai).
+You'll need an API key from OpenAI, Anthropic, Google Gemini, or xAI. You can skip entering it during setup and add it to `.env` later.
 
-## Initialize Mastra
+## Create the project
 
-You can run `create mastra` anywhere on your machine. Start the setup wizard:
+Run the interactive setup:
 
 **npm**:
 
@@ -42,32 +42,47 @@ yarn create mastra
 bunx create-mastra
 ```
 
-You'll be prompted for various configuration options, including your LLM provider and whether to enable [Observability](https://mastra.ai/docs/mastra-platform/observability) on the Mastra platform.
+The command asks for a project name, model provider, and optional API key. It then installs dependencies, installs Mastra skills for your coding assistants, and creates an initial Git commit when you aren't already inside a repository.
 
-The wizard creates a new directory for your project with a `src/mastra` folder containing an example weather agent and the following files:
+The generated `src/mastra` directory contains the Mastra entry point, agent, workspace tools, and supporting code. See the [project structure reference](https://mastra.ai/reference/project-structure) for the standard Mastra layout.
 
-- `index.ts`: Entry point for all Mastra-related code and configuration
-- `agents/weather-agent.ts`: A weather agent with a prompt that uses the tool
-- `tools/weather-tool.ts`: A tool to fetch weather for a given location
-- `workflows/weather-workflow.ts`: A workflow that runs the weather agent
-- `scorers/weather-scorer.ts`: A scorer to evaluate the weather agent's responses
+> **Tip:** Use `--template <template>` to start from a template, or `--empty` to create a minimal provider-free project. Use `--no-skills` or `--no-git` to skip automatic setup. See the [`create-mastra` reference](https://mastra.ai/reference/cli/create-mastra) for all flags.
 
-Depending on your choices, you'll also end up with [Mastra Skills](https://mastra.ai/docs/getting-started/build-with-ai) or the [MCP Docs Server](https://mastra.ai/docs/getting-started/build-with-ai) installed. Learn more about Mastra's [project structure](https://mastra.ai/reference/project-structure).
+## Test your agent
 
-> **Tip:** You can use [flags](https://mastra.ai/reference/cli/create-mastra) with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](https://mastra.ai/templates).
+Follow the terminal instructions to enter the project directory and start the development server:
 
-## Test your agent
+**npm**:
+
+```bash
+npm run dev
+```
+
+**pnpm**:
+
+```bash
+pnpm run dev
+```
+
+**Yarn**:
+
+```bash
+yarn dev
+```
+
+**Bun**:
 
-Once setup is complete, follow the instructions in your terminal to start the Mastra dev server, then open Studio at [localhost:4111](http://localhost:4111).
+```bash
+bun run dev
+```
 
-Try asking about the weather. If your API key is set up correctly, you'll get a response in Studio.
+Open [Studio at localhost:4111](http://localhost:4111), select the agent, and send a message. Add the provider API key named in `.env.example` to an `.env` file if you skipped it during setup.
 
-[Studio](https://mastra.ai/docs/studio/overview) lets you rapidly build and prototype agents without needing to build a UI. Once you're ready, you can integrate your Mastra agent into your app using the guides below.
+[Studio](https://mastra.ai/docs/studio/overview) lets you build and test agents without creating a separate UI.
 
 ## Next steps
 
-- Integrate Mastra with your frontend framework: [Next.js](https://mastra.ai/guides/getting-started/next-js), [React](https://mastra.ai/guides/getting-started/vite-react), or [Astro](https://mastra.ai/guides/getting-started/astro)
-- Read more about [Mastra's features](https://mastra.ai/docs)
-- Learn how you can [build Mastra with AI](https://mastra.ai/docs/getting-started/build-with-ai)
-- Build an agent from scratch following one of our [guides](https://mastra.ai/guides)
-- Watch conceptual guides on our [YouTube channel](https://www.youtube.com/@mastra-ai) and [subscribe](https://www.youtube.com/@mastra-ai?sub_confirmation=1)
+- Integrate Mastra with [Next.js](https://mastra.ai/guides/getting-started/next-js), [React](https://mastra.ai/guides/getting-started/vite-react), or [Astro](https://mastra.ai/guides/getting-started/astro)
+- Learn how to [build Mastra with AI](https://mastra.ai/docs/getting-started/build-with-ai)
+- Build an agent from scratch with a [guide](https://mastra.ai/guides)
+- Watch the [Mastra YouTube channel](https://www.youtube.com/@mastra-ai)

package/.docs/guides/index.md

@@ -6,7 +6,7 @@ Mastra offers a variety of guides to help you build and work with Mastra, from b
 
 ## New project
 
-The `create mastra` command is the fastest way to build your first agent. It walks you through setup and generates an example agent you can run and adapt in [Studio](https://mastra.ai/docs/studio/overview) right away. You can always integrate Mastra with your framework or UI when you’re ready.
+The `npm create mastra@latest` command is the fastest way to build your first agent. It creates a ready-to-run agent harness that you can explore and adapt in [Studio](https://mastra.ai/docs/studio/overview) right away. You can always integrate Mastra with your framework or UI when you’re ready.
 
 - [Quickstart](https://mastra.ai/guides/getting-started/quickstart)
 

package/.docs/guides/migrations/vnext-to-standard-apis.md

@@ -245,9 +245,7 @@ The following options are available in the standard `.stream()` and `generate()`
   const result = await agent.stream(messages, {
     prepareStep: ({ step, state }) => {
       console.log('About to execute step:', step)
-      return {
-        /* modified state */
-      }
+      return {/* modified state */}
     },
   })
   ```

package/.docs/models/environment-variables.md

@@ -10,6 +10,7 @@ List of required environment variables for each model provider and gateway suppo
 | [Abacus](https://mastra.ai/models/providers/abacus)                                            | `abacus/*`                 | `ABACUS_API_KEY`                                                                                      |
 | [abliteration.ai](https://mastra.ai/models/providers/abliteration-ai)                          | `abliteration-ai/*`        | `ABLIT_KEY`                                                                                           |
 | [AI-ROUTER](https://mastra.ai/models/providers/ai-router)                                      | `ai-router/*`              | `AI_ROUTER_API_KEY`                                                                                   |
+| [AKI.IO](https://mastra.ai/models/providers/aki-io)                                            | `aki-io/*`                 | `AKI_IO_API_KEY`                                                                                      |
 | [Alibaba](https://mastra.ai/models/providers/alibaba)                                          | `alibaba/*`                | `DASHSCOPE_API_KEY`                                                                                   |
 | [Alibaba (China)](https://mastra.ai/models/providers/alibaba-cn)                               | `alibaba-cn/*`             | `DASHSCOPE_API_KEY`                                                                                   |
 | [Alibaba Coding Plan](https://mastra.ai/models/providers/alibaba-coding-plan)                  | `alibaba-coding-plan/*`    | `ALIBABA_CODING_PLAN_API_KEY`                                                                         |
@@ -29,6 +30,7 @@ List of required environment variables for each model provider and gateway suppo
 | [Chutes](https://mastra.ai/models/providers/chutes)                                            | `chutes/*`                 | `CHUTES_API_KEY`                                                                                      |
 | [Clarifai](https://mastra.ai/models/providers/clarifai)                                        | `clarifai/*`               | `CLARIFAI_PAT`                                                                                        |
 | [Claudinio](https://mastra.ai/models/providers/claudinio)                                      | `claudinio/*`              | `CLAUDINIO_API_KEY`                                                                                   |
+| [ClinePass](https://mastra.ai/models/providers/cline-pass)                                     | `cline-pass/*`             | `CLINE_API_KEY`                                                                                       |
 | [CloudFerro Sherlock](https://mastra.ai/models/providers/cloudferro-sherlock)                  | `cloudferro-sherlock/*`    | `CLOUDFERRO_SHERLOCK_API_KEY`                                                                         |
 | [Cloudflare Workers AI](https://mastra.ai/models/providers/cloudflare-workers-ai)              | `cloudflare-workers-ai/*`  | `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_KEY`                                                         |
 | [Cortecs](https://mastra.ai/models/providers/cortecs)                                          | `cortecs/*`                | `CORTECS_API_KEY`                                                                                     |
@@ -132,6 +134,7 @@ List of required environment variables for each model provider and gateway suppo
 | [Tencent Token Plan](https://mastra.ai/models/providers/tencent-token-plan)                    | `tencent-token-plan/*`     | `TENCENT_TOKEN_PLAN_API_KEY`                                                                          |
 | [Tencent TokenHub](https://mastra.ai/models/providers/tencent-tokenhub)                        | `tencent-tokenhub/*`       | `TENCENT_TOKENHUB_API_KEY`                                                                            |
 | [The Grid AI](https://mastra.ai/models/providers/the-grid-ai)                                  | `the-grid-ai/*`            | `THEGRIDAI_API_KEY`                                                                                   |
+| [Thinking Machines](https://mastra.ai/models/providers/thinkingmachines)                       | `thinkingmachines/*`       | `TINKER_API_KEY`                                                                                      |
 | [Tinfoil](https://mastra.ai/models/providers/tinfoil)                                          | `tinfoil/*`                | `TINFOIL_API_KEY`                                                                                     |
 | [Together AI](https://mastra.ai/models/providers/togetherai)                                   | `togetherai/*`             | `TOGETHER_API_KEY`                                                                                    |
 | [TrustedRouter](https://mastra.ai/models/providers/trustedrouter)                              | `trustedrouter/*`          | `TRUSTEDROUTER_API_KEY`                                                                               |

package/.docs/models/gateways/netlify.md

@@ -2,7 +2,7 @@
 
 # Netlify
 
-Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 70 models through Mastra's model router.
+Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 72 models through Mastra's model router.
 
 Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
 
@@ -62,6 +62,8 @@ ANTHROPIC_API_KEY=ant-...
 | `gemini/gemini-3.1-pro-preview`             |
 | `gemini/gemini-3.1-pro-preview-customtools` |
 | `gemini/gemini-3.5-flash`                   |
+| `gemini/gemini-3.5-flash-lite`              |
+| `gemini/gemini-3.6-flash`                   |
 | `gemini/gemini-flash-latest`                |
 | `gemini/gemini-flash-lite-latest`           |
 | `openai/chat-latest`                        |