@mastra/mcp-docs-server 1.2.13-alpha.1 → 1.2.13-alpha.11

package/.docs/reference/core/getVector.md

@@ -20,5 +20,5 @@ mastra.getVector('testVectorStore')
 
 ## Related
 
-- [Vector stores overview](https://mastra.ai/docs/rag/vector-databases)
-- [RAG overview](https://mastra.ai/docs/rag/overview)
+- [Vector stores overview](https://mastra.ai/guides/rag/vector-databases)
+- [RAG overview](https://mastra.ai/guides/rag/overview)

package/.docs/reference/core/listVectors.md

@@ -20,5 +20,5 @@ This method doesn't accept any parameters.
 
 ## Related
 
-- [Vector stores overview](https://mastra.ai/docs/rag/vector-databases)
-- [RAG overview](https://mastra.ai/docs/rag/overview)
+- [Vector stores overview](https://mastra.ai/guides/rag/vector-databases)
+- [RAG overview](https://mastra.ai/guides/rag/overview)

package/.docs/reference/core/mastra-class.md

@@ -97,7 +97,7 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **notifications.dispatch.batchSize** (`number`): Maximum number of due notification records to process per dispatch run.
 
-**versions** (`VersionOverrides`): Global version overrides for sub-agent delegation. When a supervisor agent delegates to a sub-agent, these overrides determine which stored version of that sub-agent to use instead of the code-defined default. Requires the editor package to be configured. See Sub-agent versioning for details.
+**versions** (`VersionOverrides`): Global version overrides for sub-agent delegation. When a supervisor agent delegates to a sub-agent, these overrides determine which stored version of that sub-agent to use instead of the code-defined default. Requires the editor package to be configured. See Editor versioning for details.
 
 **versions.agents** (`Record<string, VersionSelector>`): A map of agent IDs to their version selectors. Each selector can target a specific version by ID or by publication status.
 
@@ -135,7 +135,7 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 Re-drives every orphaned `running` durable-agent run across all registered durable agents. Called automatically on boot when `recovery.durableAgents` is `'auto'`. You can also call it directly for manual recovery or from a scheduled task.
 
-Requires persistent storage — with an in-memory store there is nothing to recover after a process restart.
+Requires persistent storage. With an in-memory store, there's nothing to recover after a process restart.
 
 ```typescript
 const result = await mastra.recoverAllDurableAgents()

package/.docs/reference/datasets/startExperiment.md

@@ -79,6 +79,12 @@ console.log(`Status: ${summary2.status}`)
 
 **unmockedToolPolicy** (`'allow' | 'deny'`): Controls undeclared agent tool calls. allow executes them live. deny fails the item with TOOL\_MOCK\_NOT\_DECLARED before execution. An item-level value overrides this experiment default. (Default: `'allow'`)
 
+**persistence** (`ExperimentPersistencePolicy`): Controls whether this run writes experiment records and score records. Targets and scorers still execute, and results remain available in the returned summary.
+
+**persistence.experiments** (`'default' | 'none'`): Set to none to skip experiment creation, item results, progress, and terminal status writes.
+
+**persistence.scores** (`'default' | 'none'`): Set to none to skip score writes while still running scorers.
+
 ## Returns
 
 **result** (`Promise<ExperimentSummary>`): Summary of the completed experiment.

package/.docs/reference/datasets/startExperimentAsync.md

@@ -33,6 +33,10 @@ console.log(`Current status: ${experiment.status}`)
 
 Takes the same `StartExperimentConfig` as [`dataset.startExperiment()`](https://mastra.ai/reference/datasets/startExperiment).
 
+When `persistence.experiments` is set to `'none'`, `startExperimentAsync()` doesn't persist an experiment record, progress updates, or item results. Score persistence remains controlled separately by `persistence.scores`. Without an experiment event observer, the run is fire-and-forget, and the experiment API can't report whether it completed or failed.
+
+Use synchronous [`startExperiment()`](https://mastra.ai/reference/datasets/startExperiment) when the caller needs the returned summary. An experiment event observer can receive lifecycle events and the terminal summary.
+
 ## Returns
 
 **result** (`Promise<object>`): Immediate response with experiment ID.

package/.docs/reference/editor/browser-provider.md

@@ -54,7 +54,7 @@ export const myBrowserProvider: BrowserProvider<{ apiKey: string }> = {
 }
 ```
 
-Once registered, admins can pin the provider as a Builder default via [`BuilderAgentDefaults.browser`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults):
+Once registered, admins can pin the provider as a Builder default via [`BuilderAgentDefaults.browser`](https://agent-builder.mastra.ai/reference/builder-agent-defaults):
 
 ```typescript
 new MastraEditor({
@@ -72,6 +72,6 @@ new MastraEditor({
 
 ## Related
 
-- [Browser](https://mastra.ai/docs/agent-builder/browser): Concept and worked examples.
+- [Browser](https://agent-builder.mastra.ai/browser): Concept and worked examples.
 - [StorageBrowserRef](https://mastra.ai/reference/editor/storage-browser-ref): Stored configuration consumed by `createBrowser`.
 - [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor): Provider registry.

package/.docs/reference/editor/filesystem-provider.md

@@ -58,7 +58,7 @@ Once registered, admins can reference the provider from an inline workspace conf
 
 ## Related
 
-- [Workspace](https://mastra.ai/docs/agent-builder/workspace): Concept and worked examples.
+- [Workspace](https://agent-builder.mastra.ai/workspace): Concept and worked examples.
 - [StorageWorkspaceRef](https://mastra.ai/reference/editor/storage-workspace-ref): Stored configuration consumed by `createFilesystem`.
 - [SandboxProvider](https://mastra.ai/reference/editor/sandbox-provider): Sibling provider for command execution.
 - [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor): Provider registry.

package/.docs/reference/editor/mastra-editor.md

@@ -4,24 +4,17 @@
 
 The `MastraEditor` class sets up the editor system. Pass it to the `Mastra` constructor to turn on editor features like prompt blocks, agent code override, versioning, and tool providers.
 
-See the [Editor overview](https://mastra.ai/docs/editor/overview) for an introduction to what the editor does.
+See [Editor](https://mastra.ai/docs/editor/overview) for an introduction to what the editor does.
 
 ## Usage example
 
 ```typescript
 import { Mastra } from '@mastra/core'
 import { MastraEditor } from '@mastra/editor'
-import { ComposioToolProvider } from '@mastra/editor/providers/composio'
 
 export const mastra = new Mastra({
   agents: {/* your agents */},
-  editor: new MastraEditor({
-    toolProviders: {
-      composio: new ComposioToolProvider({
-        apiKey: process.env.COMPOSIO_API_KEY!,
-      }),
-    },
-  }),
+  editor: new MastraEditor(),
 })
 ```
 
@@ -43,7 +36,7 @@ export const mastra = new Mastra({
 
 **builder** (`AgentBuilderOptions`): Agent Builder configuration. See the AgentBuilderOptions reference. Omit or set enabled: false to disable the Builder.
 
-**source** (`'code' | 'db'`): Where agent overrides are stored. With 'db', overrides live in the configured storage backend and Studio shows the save and publish flow. With 'code', overrides live as per-agent JSON files on disk (routed through a local FilesystemStore) and Studio shows filesystem actions. See the Editor overview for the difference. (Default: `'db'`)
+**source** (`'code' | 'db'`): Where agent overrides are stored. With 'db', overrides live in the configured storage backend and Studio shows the save and publish flow. With 'code', overrides live as per-agent JSON files on disk (routed through a local FilesystemStore) and Studio shows filesystem actions. See Editor storage options for the difference. (Default: `'db'`)
 
 **codePath** (`string`): Directory used by the 'code' source for per-agent JSON files. Ignored when source is not 'code'. (Default: `'./mastra/editor/'`)
 
@@ -59,12 +52,12 @@ Each provider field above takes a record keyed by provider id. See the per-provi
 
 ## Agent Builder
 
-The `builder` field enables the [Agent Builder](https://mastra.ai/docs/agent-builder/overview), a browser-based UI for creating and editing stored agents. See:
+The `builder` field enables the [Agent Builder](https://agent-builder.mastra.ai/), a browser-based UI for creating and editing stored agents. See:
 
-- [Agent Builder overview](https://mastra.ai/docs/agent-builder/overview): Concepts and getting started.
-- [AgentBuilderOptions](https://mastra.ai/reference/editor/agent-builder/agent-builder-options): Full options schema.
-- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): Admin-pinned defaults for new agents.
-- [builder.configuration.agent.models](https://mastra.ai/reference/editor/agent-builder/builder-models): Model allowlist and default model.
+- [Agent Builder overview](https://agent-builder.mastra.ai/): Concepts and getting started.
+- [AgentBuilderOptions](https://agent-builder.mastra.ai/reference/agent-builder-options): Full options schema.
+- [BuilderAgentDefaults](https://agent-builder.mastra.ai/reference/builder-agent-defaults): Admin-pinned defaults for new agents.
+- [builder.configuration.agent.models](https://agent-builder.mastra.ai/reference/builder-models): Model allowlist and default model.
 
 ### Registering the Builder agent
 
@@ -85,7 +78,7 @@ export const mastra = new Mastra({
 
 The key name (`builderAgent`) is conventional. Any key works. The `@mastra/editor/ee` subpath is gated by the Mastra Enterprise Edition license at runtime.
 
-See the [Agent Builder overview](https://mastra.ai/docs/agent-builder/overview) for the full setup checklist.
+See the [Agent Builder overview](https://agent-builder.mastra.ai/#prerequisites) for the full setup checklist.
 
 ## Namespaces
 
@@ -99,7 +92,7 @@ All namespaces extend a shared CRUD base class, so they expose the same `create`
 
 **agent.getById** (`(id: string, options?: GetByIdOptions) => Promise<Agent | null>`): Return a hydrated Agent instance for a stored agent. Pass options with versionId, versionNumber, or status ("draft" | "published" | "archived") to target a specific version. Default version requests are cached.
 
-**agent.update** (`(input: StorageUpdateAgentInput) => Promise<Agent>`): Partially update a stored agent. Creates a new draft version with the provided snapshot fields (instructions, tools, memory, and so on) and invalidates the cache. Set memory to null to disable memory.
+**agent.update** (`(input: StorageUpdateAgentInput) => Promise<Agent>`): Partially update a stored agent. Creates a version from the provided snapshot fields, assigns it to activeVersionId, and invalidates the cache. Set memory to null to disable memory.
 
 **agent.delete** (`(id: string) => Promise<void>`): Delete a stored agent and remove it from the Mastra runtime registry.
 
@@ -179,6 +172,24 @@ All namespaces extend a shared CRUD base class, so they expose the same `create`
 
 **scorer.clearCache** (`(id?: string) => void`): Clear the in-memory cache for one scorer or all scorers.
 
+### Agent namespace examples
+
+Create a stored override for an existing code-defined agent:
+
+```typescript
+import { mastra } from '../mastra'
+
+const editor = mastra.getEditor()!
+
+await editor.agent.create({
+  id: 'support-agent',
+  instructions: 'You are a friendly support agent for Acme.',
+  tools: {
+    search_kb: { description: 'Search the Acme knowledge base' },
+  },
+})
+```
+
 ## Methods
 
 ### Provider access
@@ -225,4 +236,6 @@ Returns the configured source (`'code'` or `'db'`), or `undefined` when the edit
 const source = mastra.getEditor()?.getSource()
 ```
 
-Returns: `'code' | 'db' | undefined`
+Returns: `'code' | 'db' | undefined`
+
+When `source` is omitted, Editor uses the configured database storage even though `getSource()` returns `undefined`. See [Editor storage options](https://mastra.ai/docs/editor/overview) for the storage workflows and [code-source versioning](https://mastra.ai/reference/editor/versioning) for activation and Git history behavior.

package/.docs/reference/editor/prompt-blocks.md

@@ -0,0 +1,137 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Prompt blocks
+
+Prompt blocks are reusable instruction templates managed by Editor. An agent's instructions can combine inline text, embedded prompt blocks, and references to independently versioned prompt blocks.
+
+See [Prompt blocks](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
+
+## Block types
+
+| Type               | Description                                                       |
+| ------------------ | ----------------------------------------------------------------- |
+| `text`             | Free-form text stored only in the agent version                   |
+| `prompt_block`     | A prompt block embedded in the agent version                      |
+| `prompt_block_ref` | A reference to an independently stored and versioned prompt block |
+
+Referenced blocks resolve at runtime. A missing or unpublished reference is omitted from the final instructions. Resolved nonempty blocks are joined with two newlines.
+
+The following example attaches a stored block and inline text to an agent:
+
+```typescript
+import { mastra } from '../mastra'
+
+const editor = mastra.getEditor()!
+
+await editor.agent.update({
+  id: 'support-agent',
+  instructions: [
+    { type: 'prompt_block_ref', id: 'brand-voice' },
+    { type: 'text', content: 'Answer only questions about Acme products.' },
+  ],
+})
+```
+
+## Template values
+
+Templates resolve values from the request context at runtime.
+
+| Syntax                    | Request context              | Output             |
+| ------------------------- | ---------------------------- | ------------------ |
+| `{{userName}}`            | `{ userName: 'Maya' }`       | `Maya`             |
+| `{{user.name}}`           | `{ user: { name: 'Maya' } }` | `Maya`             |
+| `{{task \|\| 'request'}}` | `{}`                         | `request`          |
+| `{{missingValue}}`        | `{}`                         | `{{missingValue}}` |
+
+Variable names must begin with a letter or underscore. Fallbacks must be single-quoted or double-quoted strings. Unresolved placeholders without a fallback remain unchanged. Objects and arrays are serialized as JSON. Other values are converted to strings.
+
+Pass values through [request context](https://mastra.ai/docs/server/request-context). Editor doesn't read a separate agent `variables` field.
+
+## Display conditions
+
+A prompt block can include a display condition that controls whether it's included in the final instructions. Each condition has three parts:
+
+- **Key**: The request-context field to check, such as `user.role` or `account.plan`.
+- **Operator**: The comparison to make, such as `equals`, `contains`, or `exists`.
+- **Value**: The value to compare against. The `exists` and `not_exists` operators don't need one.
+
+For example, the condition `user.role` `equals` `admin` includes the block only when request context contains `{ user: { role: 'admin' } }`.
+
+| Operator                                       | Example                                       | The block is included when                                |
+| ---------------------------------------------- | --------------------------------------------- | --------------------------------------------------------- |
+| `equals` / `not_equals`                        | `user.role` equals `admin`                    | The field strictly equals, or doesn't equal, the value    |
+| `contains` / `not_contains`                    | `user.tags` contains `beta`                   | A string contains the value or an array contains the item |
+| `greater_than` / `less_than`                   | `order.total` greater than `100`              | The numeric field is above or below the value             |
+| `greater_than_or_equal` / `less_than_or_equal` | `account.seats` greater than or equal to `10` | The numeric field is at or beyond the value               |
+| `in` / `not_in`                                | `user.region` in `['US', 'CA']`               | The field is, or isn't, in the supplied array             |
+| `exists` / `not_exists`                        | `account.plan` exists                         | The field has, or doesn't have, a non-null value          |
+
+Groups combine conditions with `AND` or `OR`. For example, this group includes a block for admins on a paid plan:
+
+```typescript
+const rules = {
+  operator: 'AND',
+  conditions: [
+    {
+      field: 'user.role',
+      operator: 'equals',
+      value: 'admin',
+    },
+    {
+      field: 'account.plan',
+      operator: 'in',
+      value: ['pro', 'enterprise'],
+    },
+  ],
+}
+```
+
+Dot paths are supported. An empty group evaluates to `true`, and an unknown operator evaluates to `false`. The storage type supports up to three nested group levels.
+
+Blocks without conditions are always included.
+
+## Programmatic API
+
+Access prompt blocks through `mastra.getEditor().prompt`. See the [`prompt` namespace](https://mastra.ai/reference/editor/mastra-editor) for complete method signatures.
+
+Create a prompt block:
+
+```typescript
+import { mastra } from '../mastra'
+
+const editor = mastra.getEditor()!
+
+await editor.prompt.create({
+  id: 'brand-voice',
+  name: 'Brand voice',
+  description: 'Acme tone and style guidelines',
+  content: 'Write in a friendly, concise tone. Address the user as {{userName || "there"}}.',
+})
+```
+
+Update an existing block:
+
+```typescript
+await editor.prompt.update({
+  id: 'brand-voice',
+  content: 'Write in a friendly, concise tone. Greet the user by name when available.',
+})
+```
+
+`update()` creates a new draft when the content changes. Use `list()` to paginate through stored blocks, `getById()` to fetch one block, and `preview(blocks, context)` to resolve templates and conditions with draft references.
+
+## REST API
+
+The default Mastra server prefix is `/api`. A custom server prefix changes the paths below.
+
+| Method   | Path                                             | Description                  |
+| -------- | ------------------------------------------------ | ---------------------------- |
+| `GET`    | `/api/stored/prompt-blocks`                      | List stored prompt blocks    |
+| `POST`   | `/api/stored/prompt-blocks`                      | Create a stored prompt block |
+| `GET`    | `/api/stored/prompt-blocks/:storedPromptBlockId` | Get a stored prompt block    |
+| `PATCH`  | `/api/stored/prompt-blocks/:storedPromptBlockId` | Update a stored prompt block |
+| `DELETE` | `/api/stored/prompt-blocks/:storedPromptBlockId` | Delete a stored prompt block |
+
+## Version resolution
+
+Runtime references resolve the active published block. Editor previews resolve the latest draft. See [Editor versioning](https://mastra.ai/docs/editor/overview) for the shared draft, publish, and restore lifecycle.

package/.docs/reference/editor/sandbox-provider.md

@@ -57,7 +57,7 @@ Once registered, admins can reference the provider from an inline workspace conf
 
 ## Related
 
-- [Workspace](https://mastra.ai/docs/agent-builder/workspace): Concept and worked examples.
+- [Workspace](https://agent-builder.mastra.ai/workspace): Concept and worked examples.
 - [StorageWorkspaceRef](https://mastra.ai/reference/editor/storage-workspace-ref): Stored configuration consumed by `createSandbox`.
 - [FilesystemProvider](https://mastra.ai/reference/editor/filesystem-provider): Sibling provider for file access.
 - [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor): Provider registry.

package/.docs/reference/editor/storage-browser-ref.md

@@ -4,7 +4,7 @@
 
 `StorageBrowserRef` is the inline browser configuration attached to a stored agent. The `provider` id is resolved at hydration time against the [`BrowserProvider`](https://mastra.ai/reference/editor/browser-provider) registered on [`MastraEditor.browsers`](https://mastra.ai/reference/editor/mastra-editor).
 
-It's the type used by [`BuilderAgentDefaults.browser`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
+It's the type used by [`BuilderAgentDefaults.browser`](https://agent-builder.mastra.ai/reference/builder-agent-defaults) and by stored agent records.
 
 ## Usage example
 
@@ -76,7 +76,7 @@ The shape embedded under `config`. Defined in `@mastra/core/storage`.
 
 ## Related
 
-- [Browser](https://mastra.ai/docs/agent-builder/browser): Concept and worked examples.
+- [Browser](https://agent-builder.mastra.ai/browser): Concept and worked examples.
 - [BrowserProvider](https://mastra.ai/reference/editor/browser-provider): Implementer-facing provider interface.
-- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): Where this type is pinned as the Builder default.
+- [BuilderAgentDefaults](https://agent-builder.mastra.ai/reference/builder-agent-defaults): Where this type is pinned as the Builder default.
 - [StorageWorkspaceRef](https://mastra.ai/reference/editor/storage-workspace-ref): Sibling reference type for workspace configuration.

package/.docs/reference/editor/storage-workspace-ref.md

@@ -4,7 +4,7 @@
 
 `StorageWorkspaceRef` is the discriminated union used to attach a workspace to a stored agent. It either points at a workspace registered on the Mastra runtime by ID, or embeds a workspace snapshot inline.
 
-It's the type used by [`BuilderAgentDefaults.workspace`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
+It's the type used by [`BuilderAgentDefaults.workspace`](https://agent-builder.mastra.ai/reference/builder-agent-defaults) and by stored agent records.
 
 ## Usage example
 
@@ -89,7 +89,7 @@ The shape embedded under `{ type: 'inline', config }`. Defined in `@mastra/core/
 
 ## Related
 
-- [Workspace](https://mastra.ai/docs/agent-builder/workspace): Concept and worked examples.
-- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): Where this type is pinned as the Builder default.
+- [Workspace](https://agent-builder.mastra.ai/workspace): Concept and worked examples.
+- [BuilderAgentDefaults](https://agent-builder.mastra.ai/reference/builder-agent-defaults): Where this type is pinned as the Builder default.
 - [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor): Registers filesystem and sandbox providers.
 - [StorageBrowserRef](https://mastra.ai/reference/editor/storage-browser-ref): Sibling reference type for browser configuration.

package/.docs/reference/editor/tool-provider.md

@@ -4,19 +4,47 @@
 
 The `ToolProvider` interface defines how the editor discovers and resolves integration tools from external platforms. Mastra includes two built-in implementations: `ComposioToolProvider` and `ArcadeToolProvider`.
 
-See [Tools](https://mastra.ai/docs/editor/tools) for a guide on setting up tool providers.
+See [Editor tools](https://mastra.ai/docs/editor/overview) for provider setup and the Studio workflow. See [tool configuration](https://mastra.ai/reference/editor/tools) for stored selections and resolution behavior.
 
 ## ToolProvider interface
 
-Tool providers implement these methods:
+Providers expose metadata and the legacy discovery and resolution methods. Agent Builder integrations can also implement the optional VNext catalog, connection, authorization, and health methods.
 
-**listToolkits()** (`() => Promise<Toolkit[]>`): Returns a list of available toolkits (tool categories) from the provider.
+**info** (`ToolProviderInfo`): Provider ID, name, and description.
 
-**listTools(params?)** (`(params?) => Promise<Tool[]>`): Returns a list of available tools. Accepts optional filtering by toolkit, search query, and limit.
+**displayName** (`string`): Optional name shown in the tool picker. Defaults to info.name.
 
-**getToolSchema(slug)** (`(slug: string) => Promise<JSONSchema>`): Returns the JSON schema for a specific tool identified by its slug.
+**capabilities** (`ToolProviderCapabilities`): Static connection and revocation capabilities. Required for VNext providers.
 
-**resolveTools(slugs, options?)** (`(slugs: string[], options?) => Promise<Record<string, ToolAction>>`): Resolves tool slugs into executable Mastra tool actions. Built-in providers use resourceId from request context for per-user authentication.
+**defaultScope** (`'per-author' | 'caller-supplied'`): Default connection identity scope. Defaults to 'per-author' when omitted.
+
+**listToolkits()** (`() => Promise<ToolProviderListResult<ToolProviderToolkit>>`): Lists available toolkits through the legacy interface.
+
+**listTools(params?)** (`(params?: ListToolProviderToolsOptions) => Promise<ToolProviderListResult<ToolProviderToolInfo>>`): Lists tools with optional toolkit, search, and pagination filters.
+
+**getToolSchema(slug)** (`(slug: string) => Promise<Record<string, unknown> | null>`): Returns a tool input schema through the legacy interface.
+
+**resolveTools(slugs, configs?, options?)** (`(slugs: string[], configs?: Record<string, StorageToolConfig>, options?: ResolveToolProviderToolsOptions) => Promise<Record<string, ToolAction>>`): Resolves legacy tool selections into executable Mastra tools.
+
+**listToolkitsVNext()** (`() => Promise<ListToolkitsResult>`): Lists allowed toolkits for Agent Builder and Editor.
+
+**listToolsVNext(options?)** (`(options?: ListToolsOpts) => Promise<ListToolsResult>`): Lists allowed tools with toolkit, search, and pagination options.
+
+**resolveToolsVNext(options)** (`(options: ResolveToolsOpts) => Promise<Record<string, ToolAction>>`): Resolves tools for one set of slugs and one authorized connection.
+
+**authorize(options)** (`(options: AuthorizeOpts) => Promise<{ url: string; authId: string }>`): Starts an authorization flow.
+
+**listConnectionFields(options)** (`(options: { toolkit: string }) => Promise<ConnectionField[]>`): Lists provider-specific values required to authorize a toolkit.
+
+**getAuthStatus(authId)** (`(authId: string) => Promise<AuthFlowStatus>`): Returns the state of an authorization flow.
+
+**getConnectionStatus(options)** (`(options: { items: Array<{ connectionId: string; toolkit: string }> }) => Promise<Record<string, { connected: boolean }>>`): Checks whether a batch of connections is still active.
+
+**listConnections(options)** (`(options: ListConnectionsOpts) => Promise<ListConnectionsResult>`): Lists existing provider connections for a user and toolkit.
+
+**getHealth()** (`() => Promise<ToolProviderHealth>`): Returns provider configuration and reachability health.
+
+**revokeConnection(connectionId)** (`(connectionId: string) => Promise<void>`): Revokes a provider connection.
 
 ***
 
@@ -28,7 +56,7 @@ Connects to [Composio](https://composio.dev) for access to hundreds of integrati
 
 ```typescript
 import { MastraEditor } from '@mastra/editor'
-import { ComposioToolProvider } from '@mastra/editor/providers/composio'
+import { ComposioToolProvider } from '@mastra/editor/composio'
 
 const editor = new MastraEditor({
   toolProviders: {
@@ -43,13 +71,19 @@ const editor = new MastraEditor({
 
 **apiKey** (`string`): Your Composio API key.
 
+**allowedToolkits** (`readonly string[]`): Toolkit slug allowlist. Supports exact matches and suffix wildcards.
+
+**allowedTools** (`Readonly<Record<string, readonly string[]>>`): Per-toolkit tool slug allowlists. Supports exact matches and prefix wildcards.
+
+**defaultScope** (`'per-author' | 'caller-supplied'`): Connection identity scope. Defaults to per-author. (Default: `'per-author'`)
+
 ### Tool slugs
 
 Composio tools use uppercase slug format: `GITHUB_CREATE_ISSUE`, `SLACK_SEND_MESSAGE`.
 
 ### Authentication
 
-Tool execution is scoped to the `resourceId` passed through request context. The provider maps that value to the user identity required by Composio's auth flow.
+Connections use per-author scope by default. Set `defaultScope: 'caller-supplied'` to bucket authorization by the caller identity resolved from request context.
 
 ***
 
@@ -61,7 +95,7 @@ Connects to [Arcade](https://arcade.dev) for a curated tool catalog with built-i
 
 ```typescript
 import { MastraEditor } from '@mastra/editor'
-import { ArcadeToolProvider } from '@mastra/editor/providers/arcade'
+import { ArcadeToolProvider } from '@mastra/editor/arcade'
 
 const editor = new MastraEditor({
   toolProviders: {
@@ -84,4 +118,4 @@ Arcade tools use `Toolkit.ToolName` format: `Github.GetRepository`, `Slack.SendM
 
 ### Authentication
 
-Like Composio, tool execution uses `resourceId` from request context for per-user authorization. The provider maps that value to the user identity required by Arcade's auth flow.
+The legacy Arcade resolver uses `resourceId` from request context when available. It otherwise falls back to the supplied `userId`, then to a shared `default` identity. Use `default` only for intentionally shared integrations. In tenant-isolated deployments, provide a trusted, stable `resourceId` or explicit `userId`. Omitting both doesn't isolate callers.

package/.docs/reference/editor/tools.md

@@ -0,0 +1,100 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Tool configuration
+
+Editor stores tool selections as part of an agent version. A stored configuration can add registered tools, tools from integration providers, and tools from Model Context Protocol (MCP) clients.
+
+See [Editor tools](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
+
+## Tool sources
+
+| Source                                                             | Description                                                                          |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| Registered tools                                                   | Tools registered in the Mastra runtime tool registry                                 |
+| MCP clients                                                        | Tools exposed by stored local or remote MCP server configurations                    |
+| Integration tools                                                  | Tools resolved by legacy integration-provider configuration                          |
+| [Tool providers](https://mastra.ai/reference/editor/tool-provider) | Tools resolved by providers registered on `MastraEditor`, such as Composio or Arcade |
+
+Code-defined agents keep their existing tools. The [`editor` override setting](https://mastra.ai/reference/agents/agent) controls whether Editor can add and remove tools or only change descriptions.
+
+## Description overrides
+
+Each selected tool can store an agent-specific description. The description changes what the model sees without modifying the original tool definition.
+
+In description-only mode, Editor applies overrides only to tools that already exist on the code-defined agent. For MCP tools, an agent-level description takes priority over the description stored on the MCP client.
+
+If two sources resolve the same tool ID, the later source replaces the complete earlier tool, including its description. See [Resolution order](#resolution-order).
+
+## Conditional tool sets
+
+Editor can store conditional variants for the `tools`, `mcpClients`, `integrationTools`, and `toolProviders` fields. At runtime, matching variants are shallow-merged based on request-context values.
+
+The rule language uses the same operators and nesting behavior as [prompt block display conditions](https://mastra.ai/reference/editor/prompt-blocks).
+
+Conditions apply to a tool field variant or MCP client reference. Per-tool `rules` values in stored tool entries aren't evaluated by the current Editor resolver.
+
+## Stored MCP clients
+
+The `editor.mcp` namespace manages reusable MCP client configurations. See the [`mcp` namespace](https://mastra.ai/reference/editor/mastra-editor) for CRUD method signatures.
+
+`@mastra/mcp` is an optional peer dependency of `@mastra/editor`. Install it before configuring stored MCP clients so Editor can load their tools at runtime:
+
+**npm**:
+
+```bash
+npm install @mastra/mcp
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/mcp
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/mcp
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/mcp
+```
+
+### Transports
+
+| Transport | Stored configuration                                 |
+| --------- | ---------------------------------------------------- |
+| `stdio`   | `command` with optional `args`, `env`, and `timeout` |
+| HTTP      | `url` with optional `timeout`                        |
+
+Stored HTTP definitions don't accept arbitrary headers. When the reserved `mastra__authToken` value is present in request context, Editor forwards it as an `Authorization: Bearer` header.
+
+### Filtering
+
+MCP tools can be allowlisted at two levels:
+
+1. **Server level**: The stored server's `tools` map limits tools for every agent that uses the client.
+2. **Agent level**: The agent's MCP client reference limits the remaining tools for that agent.
+
+Agent-level tool names can use namespaced or bare names. An explicit empty `tools` map selects all tools. With the current resolver, omitting `tools` from an agent-level MCP reference selects none.
+
+### Namespacing
+
+MCP tools use `serverName_toolName` IDs to avoid conflicts. A `search` tool from the `docs` server becomes `docs_search`.
+
+## Resolution order
+
+Editor merges tool records in the following order. Later records replace earlier records with the same ID.
+
+1. Code-defined tools
+2. Registered stored tools
+3. MCP tools
+4. Legacy integration tools
+5. V1 tool-provider tools
+
+Standalone stored agents use the same order without code-defined tools. Static code-agent overrides stop after legacy integration tools.
+
+Use unique tool IDs across sources when possible. A collision replaces the complete earlier tool rather than merging its fields.