@mastra/mcp-docs-server 1.1.41-alpha.0 → 1.1.42-alpha.10

package/.docs/reference/client-js/agent-builder.md

@@ -0,0 +1,161 @@
+# Agent Builder API
+
+The Agent Builder API provides methods to interact with [Agent Builder](https://mastra.ai/docs/agent-builder/overview) actions on the server. Each action is a workflow exposed under `/agent-builder/:actionId/*`. The Builder must be enabled on the server via `MastraEditor.builder.enabled`, with a valid `MASTRA_EE_LICENSE` in production.
+
+## Getting all actions
+
+Retrieve a record of available Agent Builder actions:
+
+```typescript
+const actions = await mastraClient.getAgentBuilderActions()
+```
+
+Returns a `Record<string, WorkflowInfo>` keyed by action ID.
+
+## Working with a specific action
+
+Get an instance of a specific action by its ID:
+
+```typescript
+const action = mastraClient.getAgentBuilderAction('create-agent')
+```
+
+## Action methods
+
+### `details()`
+
+Retrieve metadata about an Agent Builder action:
+
+```typescript
+const info = await action.details()
+```
+
+### `createRun()`
+
+Create a new run for this action and receive a `runId`. Use the returned id with `startActionRun()`, `stream()`, `resume()`, or `observeStream()`.
+
+```typescript
+const { runId } = await action.createRun()
+```
+
+You can also pass an explicit `runId`:
+
+```typescript
+const { runId } = await action.createRun({ runId: 'my-run-id' })
+```
+
+### `startAsync()`
+
+Start the action and wait for completion. Returns the final `AgentBuilderActionResult` with `success`, `applied`, `branchName`, `message`, `validationResults`, `error`, `errors`, and `stepResults`.
+
+```typescript
+const result = await action.startAsync({
+  inputData: { agentName: 'support-bot' },
+})
+```
+
+Pass an existing `runId` as the second argument to start a previously created run:
+
+```typescript
+const { runId } = await action.createRun()
+const result = await action.startAsync({ inputData }, runId)
+```
+
+### `startActionRun()`
+
+Start an existing run without waiting for completion. Returns `{ message }`.
+
+```typescript
+const { runId } = await action.createRun()
+await action.startActionRun({ inputData }, runId)
+```
+
+### `stream()`
+
+Start an existing run and stream progress events as a `ReadableStream<{ type, payload }>`.
+
+```typescript
+const { runId } = await action.createRun()
+const stream = await action.stream({ inputData }, runId)
+
+for await (const event of stream) {
+  console.log(event.type, event.payload)
+}
+```
+
+### `resume()`
+
+Resume a suspended step on a run. Returns `{ message }`.
+
+```typescript
+await action.resume({ step: 'review', resumeData: { approved: true } }, runId)
+```
+
+### `resumeAsync()`
+
+Resume a suspended step and wait for completion. Returns an `AgentBuilderActionResult`.
+
+```typescript
+const result = await action.resumeAsync({ step: 'review', resumeData: { approved: true } }, runId)
+```
+
+### `resumeStream()`
+
+Resume a suspended step and stream subsequent events.
+
+```typescript
+const stream = await action.resumeStream({
+  runId,
+  step: 'review',
+  resumeData: { approved: true },
+})
+```
+
+### `observeStream()`
+
+Attach to an existing run, replaying cached events from the beginning, then continuing with live events. Use this to recover after a page refresh or hot reload.
+
+```typescript
+const stream = await action.observeStream({ runId })
+```
+
+### `observeStreamLegacy()`
+
+Same as `observeStream()` but uses the legacy streaming endpoint. Prefer `observeStream()` for new code.
+
+```typescript
+const stream = await action.observeStreamLegacy({ runId })
+```
+
+### `runs()`
+
+List runs for this action with optional filters.
+
+```typescript
+const runs = await action.runs({ page: 0, perPage: 20 })
+```
+
+Accepts `fromDate`, `toDate`, `page`, `perPage`, `resourceId`, and legacy `limit`/`offset`.
+
+### `runById()`
+
+Fetch a specific run by ID. Use `fields` to limit the returned payload and `withNestedWorkflows` to skip nested workflow data.
+
+```typescript
+const run = await action.runById(runId, {
+  fields: ['result', 'steps'],
+  withNestedWorkflows: false,
+})
+```
+
+### `cancelRun()`
+
+Cancel an in-flight run.
+
+```typescript
+await action.cancelRun(runId)
+```
+
+## Access control
+
+The `/agent-builder/*` routes are gated by the `agent-builder` permission resource. Calling clients need at minimum `agent-builder:read` and `agent-builder:execute`, plus any picker resources the action touches (`stored-agents`, `stored-skills`, `tools`, `workflows`, `memory`). See [Access control](https://mastra.ai/docs/agent-builder/access-control) for the full grant list.

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

@@ -326,7 +326,7 @@ response.processDataStream({
 
 ### `approveToolCall()`
 
-Approve a pending tool call that requires human confirmation:
+Approve a pending tool call and return a continuation stream. Use this when you are rendering the resumed chunks from the approval response.
 
 ```typescript
 const response = await agent.approveToolCall({
@@ -341,9 +341,26 @@ response.processDataStream({
 })
 ```
 
+### `sendToolApproval()`
+
+Approve or decline a pending tool call for a subscribed thread. Use this with `subscribeToThread()` when the resumed chunks should arrive through the existing thread subscription instead of a separate continuation stream.
+
+```typescript
+const result = await agent.sendToolApproval({
+  resourceId: 'user-123',
+  threadId: 'thread-456',
+  toolCallId: 'tool-call-456',
+  approved: true,
+})
+
+console.log(result.accepted)
+```
+
+Returns `{ accepted: true, runId: string, toolCallId?: string }`.
+
 ### `declineToolCall()`
 
-Decline a pending tool call that requires human confirmation:
+Decline a pending tool call and return a continuation stream. Use this when you are rendering the resumed chunks from the decline response.
 
 ```typescript
 const response = await agent.declineToolCall({

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

@@ -73,6 +73,10 @@ You can also pass `requestContext` as a `Record<string, any>`.
 
 **getWorkflow(workflowId)** (`Workflow`): Retrieves a specific workflow instance by ID.
 
+**getAgentBuilderActions()** (`Promise<Record<string, WorkflowInfo>>`): Returns all available Agent Builder actions. See \[Agent Builder API]\(/reference/client-js/agent-builder).
+
+**getAgentBuilderAction(actionId)** (`AgentBuilder`): Retrieves an Agent Builder action by ID. See \[Agent Builder API]\(/reference/client-js/agent-builder).
+
 **responses** (`Responses`): Provides OpenAI-style Responses API helpers with \`create()\`, \`retrieve()\`, \`stream()\`, and \`delete()\`.
 
 **conversations** (`Conversations`): Provides conversation helpers with \`create()\`, \`retrieve()\`, \`delete()\`, and \`items.list()\`.

package/.docs/reference/configuration.md

@@ -30,7 +30,7 @@ export const mastra = new Mastra({
       id: 'weather-agent',
       name: 'Weather Agent',
       instructions: 'You help with weather information',
-      model: 'openai/gpt-5.4',
+      model: 'openai/gpt-5.5',
     }),
   },
 })

package/.docs/reference/editor/agent-builder/agent-builder-options.md

@@ -0,0 +1,74 @@
+# AgentBuilderOptions
+
+`AgentBuilderOptions` configures the Agent Builder. Pass it as `MastraEditor.builder` to enable the Builder UI, toggle visible surfaces, pin admin defaults, and opt into skill registries.
+
+See the [Configuration](https://mastra.ai/docs/agent-builder/configuration) page for concepts and worked examples.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+
+new MastraEditor({
+  builder: {
+    enabled: true,
+    features: {
+      agent: { browser: false },
+    },
+    configuration: {
+      agent: {
+        memory: { observationalMemory: true },
+        models: {
+          allowed: [
+            { provider: 'openai', modelId: 'gpt-5.4-mini' },
+            { provider: 'openai', modelId: 'gpt-5.4' },
+            { provider: 'anthropic', modelId: 'claude-opus-4-7' },
+          ],
+        },
+      },
+    },
+    registries: {
+      skillsSh: { enabled: true },
+    },
+  },
+})
+```
+
+## Properties
+
+**enabled** (`boolean`): Master switch. When false, the Builder UI is disabled and \`MastraEditor.resolveBuilder()\` returns undefined. (Default: `true`)
+
+**features** (`{ agent?: AgentFeatures }`): UI toggles. Each key on \`features.agent\` defaults to true when omitted.
+
+**features.agent.tools** (`boolean`): Show the tools tab in the agent editor.
+
+**features.agent.agents** (`boolean`): Show the sub-agents picker in the agent editor.
+
+**features.agent.workflows** (`boolean`): Show the workflows picker in the agent editor.
+
+**features.agent.skills** (`boolean`): Show the skills tab and library for the agent.
+
+**features.agent.memory** (`boolean`): Show the memory configuration in the agent editor.
+
+**features.agent.model** (`boolean`): Show the model picker in the agent editor. When false, the admin-pinned default model applies.
+
+**features.agent.browser** (`boolean`): Show the browser tab. Resolves to true only when a valid browser provider is registered on \`MastraEditor.browsers\`; otherwise it is downgraded to false and a warning is logged.
+
+**features.agent.avatarUpload** (`boolean`): Allow end users to upload an avatar for stored agents.
+
+**features.agent.favorites** (`boolean`): Show favorite agents and skills with per-user state and aggregate counts.
+
+**configuration** (`{ agent?: BuilderAgentDefaults }`): Admin-pinned defaults applied to every Builder-created agent. End users cannot override these values. See the BuilderAgentDefaults reference for the full schema.
+
+**registries** (`{ skillsSh?: { enabled: boolean } }`): Opt-in third-party skill registries. When no registry is enabled, the Builder hides registry browse UI.
+
+**registries.skillsSh** (`{ enabled: boolean }`): Enable the skills.sh registry. When enabled, the Builder shows registry browse UI for skills.sh skills.
+
+**registries.skillsSh.enabled** (`boolean`): Set to \`true\` to opt in. Defaults to \`false\`.
+
+## Related
+
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — concept and worked examples.
+- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — full schema for `configuration.agent`.
+- [builder.configuration.agent.models](https://mastra.ai/reference/editor/agent-builder/builder-models) — model allowlist and default model.
+- [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor) — the parent surface that hosts `builder`.

package/.docs/reference/editor/agent-builder/builder-agent-defaults.md

@@ -0,0 +1,77 @@
+# BuilderAgentDefaults
+
+`BuilderAgentDefaults` describes the admin-pinned defaults applied to every agent the Agent Builder produces. Pass it as `builder.configuration.agent`. End users can't override these values from the Builder UI.
+
+See [Configuration](https://mastra.ai/docs/agent-builder/configuration) and [Memory](https://mastra.ai/docs/agent-builder/memory) for worked examples.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+
+new MastraEditor({
+  builder: {
+    enabled: true,
+    configuration: {
+      agent: {
+        memory: { observationalMemory: true },
+        workspace: {
+          type: 'inline',
+          config: {
+            name: 'builder-workspace',
+            filesystem: {
+              provider: 'local',
+              config: { basePath: './workspace' },
+            },
+          },
+        },
+        models: {
+          allowed: [
+            { provider: 'openai', modelId: 'gpt-5.4-mini' },
+            { provider: 'openai', modelId: 'gpt-5.4' },
+            { provider: 'anthropic', modelId: 'claude-opus-4-7' },
+          ],
+        },
+        tools: { allowed: ['weather-info'] },
+        agents: { allowed: ['weather-agent'] },
+        workflows: { allowed: ['greet-workflow'] },
+      },
+    },
+  },
+})
+```
+
+## Properties
+
+**memory** (`SerializedMemoryConfig`): Default memory configuration for new agents. Pass \`{ observationalMemory: true }\` to enable long-lived fact extraction. Requires \`Mastra.storage\`. See the SerializedMemoryConfig reference for the full schema.
+
+**workspace** (`StorageWorkspaceRef`): Default workspace reference for new agents. Pass \`{ type: 'inline', config }\` to embed a snapshot, or \`{ type: 'id', workspaceId }\` to point at a workspace registered on \`Mastra.workspace\`. See the StorageWorkspaceRef reference for both variants.
+
+**browser** (`StorageBrowserRef`): Default browser configuration for new agents. Pass \`{ type: 'inline', config: { provider } }\` to attach a registered browser provider. See the StorageBrowserRef reference for the full schema.
+
+**models** (`{ allowed?: ProviderModelEntry[]; default?: DefaultModelEntry }`): Model allowlist and default applied to every Builder-created agent. See the BuilderModels reference for the full schema and validation rules.
+
+**models.allowed** (`ProviderModelEntry[]`): Allowlist of providers and models. Omit to allow every registered model. ProviderModelEntry is a discriminated union (known providers vs. custom).
+
+**models.default** (`DefaultModelEntry`): Pre-selected model on new-agent create. Required when the model picker is hidden. DefaultModelEntry requires \`provider\` and \`modelId\`, with an optional \`kind\`.
+
+**tools** (`{ allowed?: string[] }`): Allowlist of tool IDs visible in the Builder tools picker. Unknown IDs are dropped and surfaced as warnings.
+
+**tools.allowed** (`string[]`): Allowlist of \`tool.id\` values. Omit for unrestricted, pass \`\[]\` to lock the picker down, pass \`\[...ids]\` to restrict to the listed tools.
+
+**agents** (`{ allowed?: string[] }`): Allowlist of agent IDs visible in the Builder sub-agents picker. Unknown IDs are dropped and surfaced as warnings.
+
+**agents.allowed** (`string[]`): Allowlist of \`Agent.id\` values. Omit for unrestricted, pass \`\[]\` to lock the picker down, pass \`\[...ids]\` to restrict to the listed agents.
+
+**workflows** (`{ allowed?: string[] }`): Allowlist of workflow IDs visible in the Builder workflows picker. Unknown IDs are dropped and surfaced as warnings.
+
+**workflows.allowed** (`string[]`): Allowlist of \`workflow\.id\` values. Omit for unrestricted, pass \`\[]\` to lock the picker down, pass \`\[...ids]\` to restrict to the listed workflows.
+
+## Related
+
+- [AgentBuilderOptions](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — the parent options object.
+- [builder.configuration.agent.models](https://mastra.ai/reference/editor/agent-builder/builder-models) — admin-facing model allowlist and default.
+- [SerializedMemoryConfig](https://mastra.ai/reference/memory/serialized-memory-config) — memory shape for new agents.
+- [StorageWorkspaceRef](https://mastra.ai/reference/editor/storage-workspace-ref) — workspace reference shape.
+- [StorageBrowserRef](https://mastra.ai/reference/editor/storage-browser-ref) — browser reference shape.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — concept and worked examples.

package/.docs/reference/editor/agent-builder/builder-models.md

@@ -0,0 +1,64 @@
+# builder.configuration.agent.models
+
+`builder.configuration.agent.models` is the admin-facing model policy input on `AgentBuilderOptions`. It controls which providers and models the Agent Builder exposes, and which model is pre-selected on new-agent create.
+
+See [Model policy](https://mastra.ai/docs/agent-builder/model-policy) for concepts and worked examples.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+
+new MastraEditor({
+  builder: {
+    enabled: true,
+    configuration: {
+      agent: {
+        models: {
+          allowed: [
+            { provider: 'openai', modelId: 'gpt-5.4-mini' },
+            { provider: 'openai', modelId: 'gpt-5.4' },
+            { provider: 'anthropic', modelId: 'claude-opus-4-7' },
+          ],
+        },
+      },
+    },
+  },
+})
+```
+
+## Properties
+
+**allowed** (`ProviderModelEntry[]`): Allowlist of providers and models. Omit to allow every registered model. When non-empty, only the listed entries are selectable in the Builder.
+
+**allowed.provider** (`Provider`): Provider id from the generated provider registry (for example, \`openai\`, \`anthropic\`).
+
+**allowed.modelId** (`ModelForProvider<Provider>`): Specific model id for that provider. Omit to allow every model under the provider.
+
+**allowed.kind** (`'custom'`): Discriminant marking this entry as a gateway or self-hosted provider not in the registry.
+
+**allowed.provider** (`string`): Provider id for the custom provider.
+
+**allowed.modelId** (`string`): Specific model id under the custom provider. Omit to allow every model under it.
+
+**default** (`DefaultModelEntry`): Pre-selected model on new-agent create. Same shape as \`ProviderModelEntry\`, but \`modelId\` is required. Must satisfy the \`allowed\` list when set.
+
+**default.provider** (`Provider | string`): Provider id. Use a \`Provider\` literal for known providers, or any \`string\` with \`kind: 'custom'\`.
+
+**default.modelId** (`string`): Required model id. Points at a specific model, not a whole provider.
+
+**default.kind** (`'custom'`): Set to \`custom\` when targeting a provider that isn't in the generated registry.
+
+## Validation rules
+
+Mastra validates the admin policy at server boot. Violations surface as warnings on `GET /editor/builder/settings.modelPolicyWarnings`.
+
+- `allowed` empty or omitted: no restriction. Every registered model is available.
+- When `allowed` is non-empty and a `default` is set: `default` must satisfy `isModelAllowed(allowed, default)`. A `default` that fails this check is dropped and surfaced as a warning.
+- To hide the end-user model picker, set `features.agent.model: false` in [AgentBuilderOptions](https://mastra.ai/reference/editor/agent-builder/agent-builder-options). When the picker is hidden, provide a `default` so new agents resolve a model.
+
+## Related
+
+- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — parent object containing `models`.
+- [AgentBuilderOptions](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — the top-level Builder options.
+- [Model policy](https://mastra.ai/docs/agent-builder/model-policy) — concept and worked examples.

package/.docs/reference/editor/blob-store-provider.md

@@ -0,0 +1,59 @@
+# BlobStoreProvider
+
+`BlobStoreProvider` is the interface a package implements to register a blob store with [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor). Blob stores hold content-addressable skill blobs and other large artifacts produced by the editor.
+
+The built-in `storage` provider uses the configured storage backend's `blobs` domain. External providers (for example, S3) are supplied via `MastraEditorConfig.blobStores`.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+import { s3BlobStoreProvider } from '@mastra/s3'
+
+new MastraEditor({
+  blobStores: {
+    [s3BlobStoreProvider.id]: s3BlobStoreProvider,
+  },
+})
+```
+
+## Properties
+
+**id** (`string`): Unique provider identifier (for example, \`"storage"\`, \`"s3"\`).
+
+**name** (`string`): Human-readable name for UI display.
+
+**description** (`string`): Short description.
+
+**configSchema** (`Record<string, unknown>`): JSON Schema describing provider-specific configuration. Used by the UI to render config forms.
+
+**createBlobStore** (`(config: TConfig) => BlobStore | Promise<BlobStore>`): Create a runtime \`BlobStore\` instance from the stored config. Called when the editor resolves a blob store via \`MastraEditor.resolveBlobStore(providerId, config)\`.
+
+## Implementing a provider
+
+```typescript
+import type { BlobStore, BlobStoreProvider } from '@mastra/core/editor'
+
+export const myBlobStoreProvider: BlobStoreProvider<{ bucket: string; region: string }> = {
+  id: 'my-blob-store',
+  name: 'My Blob Store',
+  description: 'Object-store-backed blob storage.',
+  configSchema: {
+    type: 'object',
+    required: ['bucket', 'region'],
+    properties: {
+      bucket: { type: 'string' },
+      region: { type: 'string' },
+    },
+  },
+  async createBlobStore(config): Promise<BlobStore> {
+    return createMyBlobStore({ bucket: config.bucket, region: config.region })
+  },
+}
+```
+
+When no `providerId` is passed to `MastraEditor.resolveBlobStore()`, the editor falls back to the storage backend's `blobs` domain.
+
+## Related
+
+- [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor) — provider registry and `resolveBlobStore()` method.

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

@@ -0,0 +1,75 @@
+# BrowserProvider
+
+`BrowserProvider` is the interface a package implements to register a browser with [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor). The editor calls `createBrowser(config)` at agent hydration time, using the `provider` id from the stored [`StorageBrowserRef`](https://mastra.ai/reference/editor/storage-browser-ref) as the lookup key.
+
+There are no built-in browser providers. To use the `browser` feature in the Agent Builder, register a provider package (for example, `@mastra/stagehand`).
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+import { stagehandBrowserProvider } from '@mastra/stagehand'
+
+new MastraEditor({
+  browsers: {
+    [stagehandBrowserProvider.id]: stagehandBrowserProvider,
+  },
+})
+```
+
+## Properties
+
+**id** (`string`): Unique provider identifier (for example, \`"stagehand"\`). Must match \`StorageBrowserConfig.provider\` on every stored agent that uses this provider.
+
+**name** (`string`): Human-readable name for UI display.
+
+**description** (`string`): Short description shown in the Agent Builder browser picker.
+
+**configSchema** (`Record<string, unknown>`): JSON Schema describing provider-specific configuration. Used by the UI to render config forms.
+
+**createBrowser** (`(config: TConfig) => MastraBrowser | Promise<MastraBrowser>`): Create a runtime \`MastraBrowser\` instance from the stored config. Called once per agent hydration; the resulting instance is cached alongside the agent.
+
+## Implementing a provider
+
+```typescript
+import type { BrowserProvider, MastraBrowser } from '@mastra/core/editor'
+
+export const myBrowserProvider: BrowserProvider<{ apiKey: string }> = {
+  id: 'my-browser',
+  name: 'My Browser',
+  description: 'Headless browser for agent use.',
+  configSchema: {
+    type: 'object',
+    properties: {
+      apiKey: { type: 'string' },
+    },
+    required: ['apiKey'],
+  },
+  async createBrowser(config): Promise<MastraBrowser> {
+    // construct and return a MastraBrowser instance
+    return createMastraBrowser({ apiKey: config.apiKey })
+  },
+}
+```
+
+Once registered, admins can pin the provider as a Builder default via [`BuilderAgentDefaults.browser`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults):
+
+```typescript
+new MastraEditor({
+  browsers: { [myBrowserProvider.id]: myBrowserProvider },
+  builder: {
+    enabled: true,
+    configuration: {
+      agent: {
+        browser: { type: 'inline', config: { provider: 'my-browser' } },
+      },
+    },
+  },
+})
+```
+
+## Related
+
+- [Browser](https://mastra.ai/docs/agent-builder/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

@@ -0,0 +1,62 @@
+# FilesystemProvider
+
+`FilesystemProvider` is the interface a package implements to register a filesystem with [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor). The editor calls `createFilesystem(config)` at workspace hydration time, using the `provider` id from the stored [`StorageWorkspaceRef`](https://mastra.ai/reference/editor/storage-workspace-ref) filesystem config as the lookup key.
+
+The built-in `local` filesystem provider is auto-registered. External providers (for example, S3 or GCS) are supplied via `MastraEditorConfig.filesystems`.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+import { s3FilesystemProvider } from '@mastra/s3'
+
+new MastraEditor({
+  filesystems: {
+    [s3FilesystemProvider.id]: s3FilesystemProvider,
+  },
+})
+```
+
+## Properties
+
+**id** (`string`): Unique provider identifier (for example, \`"local"\`, \`"s3"\`). Must match \`StorageFilesystemConfig.provider\` on every stored workspace that uses this provider.
+
+**name** (`string`): Human-readable name for UI display.
+
+**description** (`string`): Short description shown in the workspace filesystem picker.
+
+**configSchema** (`Record<string, unknown>`): JSON Schema describing provider-specific configuration. Used by the UI to render config forms.
+
+**createFilesystem** (`(config: TConfig) => WorkspaceFilesystem | Promise<WorkspaceFilesystem>`): Create a runtime \`WorkspaceFilesystem\` instance from the stored config. Called at workspace hydration time.
+
+## Implementing a provider
+
+```typescript
+import type { FilesystemProvider, WorkspaceFilesystem } from '@mastra/core/editor'
+
+export const myFilesystemProvider: FilesystemProvider<{ bucket: string; region: string }> = {
+  id: 'my-fs',
+  name: 'My Filesystem',
+  description: 'Object-store-backed filesystem.',
+  configSchema: {
+    type: 'object',
+    required: ['bucket', 'region'],
+    properties: {
+      bucket: { type: 'string' },
+      region: { type: 'string' },
+    },
+  },
+  async createFilesystem(config): Promise<WorkspaceFilesystem> {
+    return createMyFilesystem({ bucket: config.bucket, region: config.region })
+  },
+}
+```
+
+Once registered, admins can reference the provider from an inline workspace config or a stored [`StorageWorkspaceRef`](https://mastra.ai/reference/editor/storage-workspace-ref).
+
+## Related
+
+- [Workspace](https://mastra.ai/docs/agent-builder/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.