# Mastra Class

The Mastra class has been restructured to restrict top-level imports and replace direct property access with getter methods.

## Changed

### Top-level imports to subpath imports

The main `@mastra/core` index file now only exports `Mastra` and `Config`. All other exports have been moved to subpath imports. This change improves tree-shaking and reduces bundle size by allowing bundlers to eliminate unused code.

To migrate, update all imports from `@mastra/core` to use the appropriate subpath.

```diff
- import { Mastra, Agent, Workflow, createTool } from '@mastra/core';
+ import { Mastra, type Config } from '@mastra/core';
+ import { Agent } from '@mastra/core/agent';
+ import { Workflow } from '@mastra/core/workflows';
+ import { createTool } from '@mastra/core/tools';
```

> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
>
> ```bash
> npx @mastra/codemod@latest v1/mastra-core-imports .
> ```

### `experimental_auth` to `auth`

The experimental auth configuration has been promoted to stable. This change reflects that the auth API is now stable and production-ready.

To migrate, rename the `experimental_auth` key to `auth` in your Mastra configuration.

```diff
const mastra = new Mastra({
-   experimental_auth: {
+   auth: {
      provider: workos,
    },
  });
```

> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
>
> ```bash
> npx @mastra/codemod@latest v1/experimental-auth .
> ```

### Required `id` parameter for all mastra primitives

All storages, vector stores, agents, workflows, mcpServers, processors, scorers, and tools now require an `id` parameter during initialization. This enables the standardized Mastra API and prevents ID conflicts.

All these primitives also now have `get`, `list`, and `add` functions.

To migrate, add an `id` parameter to all storage and vector store instantiations. When using the same storage/vector class multiple times, ensure each instance has a unique ID.

```diff
- const storage = new LibSQLStore({
-   url: ':memory:',
- });
+ const storage = new LibSQLStore({
+   id: 'my-app-storage',
+   url: ':memory:',
+ });

- const vector = new PgVector({
-   connectionString: process.env.DATABASE_URL,
- });
+ const vector = new PgVector({
+   id: 'my-app-vector',
+   connectionString: process.env.DATABASE_URL,
+ });
```

When using separate instances for different purposes, use descriptive unique IDs:

```diff
const agentMemory = new Memory({
    storage: new LibSQLStore({
-     url: 'file:./agent.db',
+     id: 'weather-agent-memory-storage',
+     url: 'file:./agent.db',
    }),
  });

  const mastra = new Mastra({
    storage: new LibSQLStore({
+     id: 'mastra-storage',
      url: ':memory:',
    }),
  });
```

### Primitive plural APIs changes from `get<primitives>` to `list<primitive>`

`get*` functions that returned all instances of a primitive have been renamed to `list*` to better reflect their purpose.

```diff
- const agents = mastra.getAgents();
+ const agents = mastra.listAgents();
- const vectors = mastra.getVectors();
+ const vectors = mastra.listVectors();
- const workflows = mastra.getWorkflows();
+ const workflows = mastra.listWorkflows();
- const scorers = mastra.getScorers();
+ const scorers = mastra.listScorers();
- const mcpServers = mastra.getMCPServers();
+ const mcpServers = mastra.listMCPServers();
- const logsByRunId = await mastra.getLogsByRunId({ runId: 'id', transportId: 'id' });
+ const logsByRunId = await mastra.listLogsByRunId({ runId: 'id', transportId: 'id' });
- const logs = await mastra.getLogs('transportId');
+ const logs = await mastra.listLogs('transportId');
```

> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
>
> ```bash
> npx @mastra/codemod@latest v1/mastra-plural-apis .
> ```

### Each primitive has a `getById` and a `get` function

```typescript
mastra.getMCPServer('myServer');          // Works (registry key)
mastra.getMCPServerById('my-mcp-server'); // Works (intrinsic ID)
```

### Tool registration now uses intrinsic IDs

When tools are auto-registered from agents or MCP servers to the Mastra instance, they now use the tool's intrinsic `id` instead of the configuration object key. This prevents collisions when multiple agents/MCP servers have tools with the same configuration key.

To migrate, update any code that references tools by their configuration keys to use the tool's intrinsic ID instead.

```diff
const agent = new Agent({
    id: 'agent1',
    tools: {
      searchTool: weatherSearchTool,
    },
  });

- mastra.getTool('searchTool');
+ mastra.getTool(weatherSearchTool.id);
```