@mastra/core/dist/docs/references/reference-editor-mastra-editor.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# MastraEditor class

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.

## 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!,
      }),
    },
  }),
})
```

## Constructor parameters

**logger** (`Logger`): Logger instance. Falls back to the Mastra instance logger if not set.

**toolProviders** (`Record<string, ToolProvider>`): Integration tool providers keyed by ID (for example, Composio or Arcade). Lets agents use third-party tools added through the editor. (Default: `{}`)

**processorProviders** (`Record<string, ProcessorProvider>`): Processor providers for configurable input/output processing (for example, moderation or token limiting). Built-in providers are always included. (Default: `{}`)

**filesystems** (`Record<string, FilesystemProvider>`): Filesystem providers for file access (for example, S3 or GCS). A local filesystem provider is always included. (Default: `{}`)

**sandboxes** (`Record<string, SandboxProvider>`): Sandbox providers for code execution (for example, E2B). A local sandbox provider is always included. (Default: `{}`)

**blobStores** (`Record<string, BlobStoreProvider>`): Blob storage providers for binary data (for example, S3). Falls back to the Mastra storage blob store if no provider is specified. (Default: `{}`)

## Namespaces

The editor exposes namespaces for managing different entity types. Access them from any Mastra instance with `mastra.getEditor()` and call the CRUD methods directly in application code, or rely on the Mastra server routes that use them under the hood.

All namespaces extend a shared CRUD base class, so they expose the same `create`, `getById`, `update`, `delete`, `list`, `listResolved`, and `clearCache` methods. The namespace-specific property tables below also document any additional methods.

**agent** (`EditorAgentNamespace`): CRUD operations and version management for stored agents. Handles applying stored overrides to code-defined agents.

**agent.create** (`(input: StorageCreateAgentInput) => Promise<Agent>`): Create a new stored agent and return a hydrated Agent instance. Accepts an id, authorId, metadata, and the initial snapshot (name, description, instructions, model, tools, memory, and so on).

**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.delete** (`(id: string) => Promise<void>`): Delete a stored agent and remove it from the Mastra runtime registry.

**agent.list** (`(args?: StorageListAgentsInput) => Promise<StorageListAgentsOutput>`): List stored agents with optional pagination, orderBy, authorId, and metadata filters. Returns raw stored snapshots.

**agent.listResolved** (`(args?: StorageListAgentsInput) => Promise<StorageListAgentsResolvedOutput>`): Same as list, but returns fully resolved configurations with references dereferenced.

**agent.applyStoredOverrides** (`(agent: Agent, options?: { versionId?: string; status?: "draft" | "published" }) => Promise<Agent>`): Mutate a code-defined agent in place to apply any stored overrides (instructions, tools, variables). Called internally by mastra.getAgent() — you rarely call it directly.

**agent.clone** (`(agent: Agent, options: { newId: string; newName?: string; metadata?: Record<string, unknown>; authorId?: string; requestContext?: RequestContext; }) => Promise<Agent>`): Create a new stored agent by cloning an existing agent.

**agent.clearCache** (`(agentId?: string) => void`): Clear the in-memory cache for one agent or all agents. Called automatically after mutations.

**prompt** (`EditorPromptNamespace`): CRUD operations for prompt blocks. Includes a preview method for resolving instruction blocks with draft content.

**prompt.create** (`(input: StorageCreatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>`): Create a new stored prompt block. Accepts an id, authorId, metadata, and the initial snapshot (name, description, content, rules, requestContextSchema).

**prompt.getById** (`(id: string, options?: GetByIdOptions) => Promise<StorageResolvedPromptBlockType | null>`): Return a resolved prompt block. Pass options to target a specific version or status.

**prompt.update** (`(input: StorageUpdatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>`): Partially update a stored prompt block. Creates a new draft version with the provided snapshot fields.

**prompt.delete** (`(id: string) => Promise<void>`): Delete a stored prompt block and remove it from the Mastra runtime registry.

**prompt.list** (`(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksOutput>`): List stored prompt blocks with optional pagination, orderBy, authorId, metadata, and status filters.

**prompt.listResolved** (`(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksResolvedOutput>`): Same as list, but returns fully resolved prompt block content.

**prompt.preview** (`(blocks: AgentInstructionBlock[], context: Record<string, unknown>) => Promise<string>`): Resolve an array of instruction blocks against a context, rendering template variables and evaluating display conditions. Includes draft content for referenced prompt blocks.

**prompt.clearCache** (`(id?: string) => void`): Clear the in-memory cache for one prompt block or all prompt blocks.

**mcp** (`EditorMCPNamespace`): CRUD operations for stored MCP client configurations.

**mcp.create** (`(input: StorageCreateMCPClientInput) => Promise<MCPClient>`): Create a new stored MCP client. Accepts an id, authorId, metadata, and the initial snapshot (servers, tool filtering).

**mcp.getById** (`(id: string, options?: GetByIdOptions) => Promise<MCPClient | null>`): Return a hydrated MCPClient instance for a stored MCP client.

**mcp.update** (`(input: StorageUpdateMCPClientInput) => Promise<MCPClient>`): Partially update a stored MCP client and invalidate the cache.

**mcp.delete** (`(id: string) => Promise<void>`): Delete a stored MCP client and remove it from the Mastra runtime registry.

**mcp.list** (`(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsOutput>`): List stored MCP clients with optional pagination and filters.

**mcp.listResolved** (`(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsResolvedOutput>`): Same as list, but returns fully resolved MCP client configurations.

**mcp.clearCache** (`(id?: string) => void`): Clear the in-memory cache for one MCP client or all MCP clients.

**mcpServer** (`EditorMCPServerNamespace`): CRUD operations for MCP server configurations.

**mcpServer.create** (`(input: StorageCreateMCPServerInput) => Promise<MCPServerBase>`): Create a new stored MCP server configuration and return a hydrated server instance.

**mcpServer.getById** (`(id: string, options?: GetByIdOptions) => Promise<MCPServerBase | null>`): Return a hydrated MCP server for a given id.

**mcpServer.update** (`(input: StorageUpdateMCPServerInput) => Promise<MCPServerBase>`): Partially update a stored MCP server configuration.

**mcpServer.delete** (`(id: string) => Promise<void>`): Delete a stored MCP server configuration.

**mcpServer.list** (`(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersOutput>`): List stored MCP server configurations.

**mcpServer.listResolved** (`(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersResolvedOutput>`): Same as list, but returns fully resolved server configurations.

**mcpServer.clearCache** (`(id?: string) => void`): Clear the in-memory cache for one MCP server or all MCP servers.

**scorer** (`EditorScorerNamespace`): CRUD operations for scorer configurations.

**scorer.create** (`(input: StorageCreateScorerInput) => Promise<MastraScorer>`): Create a new stored scorer and return a hydrated MastraScorer instance.

**scorer.getById** (`(id: string, options?: GetByIdOptions) => Promise<MastraScorer | null>`): Return a hydrated scorer for a given id.

**scorer.update** (`(input: StorageUpdateScorerInput) => Promise<MastraScorer>`): Partially update a stored scorer.

**scorer.delete** (`(id: string) => Promise<void>`): Delete a stored scorer and remove it from the Mastra runtime registry.

**scorer.list** (`(args?: StorageListScorersInput) => Promise<StorageListScorersOutput>`): List stored scorers with optional pagination and filters.

**scorer.listResolved** (`(args?: StorageListScorersInput) => Promise<StorageListScorersResolvedOutput>`): Same as list, but returns fully resolved scorer configurations.

**scorer.clearCache** (`(id?: string) => void`): Clear the in-memory cache for one scorer or all scorers.

## Methods

### Provider access

#### `getToolProvider(id)`

Returns a registered tool provider by its ID.

```typescript
const composio = mastra.getEditor()?.getToolProvider('composio')
```

#### `getToolProviders()`

Returns all registered tool providers as a `Record<string, ToolProvider>`.

#### `getProcessorProvider(id)`

Returns a registered processor provider by its ID.

#### `getProcessorProviders()`

Returns all registered processor providers.

#### `getFilesystemProviders()`

Returns all registered filesystem providers.

#### `getSandboxProviders()`

Returns all registered sandbox providers.

#### `getBlobStoreProviders()`

Returns all registered blob store providers.