A new Workspace capability unifies agent-accessible filesystem operations, sandboxed command/code execution, keyword/semantic/hybrid search, and SKILL.md discovery with safety controls (read-only, approval flows, read-before-write guards). The Workspace is exposed end-to-end: core Workspace class (@mastra/core/workspace), server API endpoints (/workspaces/...), and new @mastra/client-js workspace client methods (files, skills, references, search).

Observability & Streaming Improvements (Trace Status, Better Spans, Tool Approval Tracing)

Tracing is more actionable: listTraces now returns a status (success|error|running), spans are cleaner (inherit entity metadata, remove internal spans, emit model chunk spans for all streaming chunks), and tool approval requests are visible in traces. Token accounting for Langfuse/PostHog is corrected (cached tokens separated) and default tracing tags are preserved across exporters.

Server Adapters: Serverless MCP Support + Explicit Route Auth Controls

Express/Fastify/Hono/Koa adapters gain (notably ) to run MCP HTTP transport statelessly in serverless/edge environments without overriding response handling. Adapters and also add explicit per route (defaulting to protected), improved custom-route auth enforcement (including path params), and corrected route prefix replacement/normalization.

mcpOptions

serverless: true

@mastra/server

requiresAuth

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

// Working memory is loaded but agent cannot update it
const response = await agent.generate("What do you know about me?", {
  memory: {
    thread: "conversation-123",
    resource: "user-alice-456",
    options: { readOnly: true },
  },
});

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  bm25: true,
});

const agent = new Agent({
  workspace,
  // Agent automatically receives workspace tools
});

const agent = new Agent({
  voice: new CompositeVoice({ output: new OpenAIVoice() }),
});

const agent = new Agent({
  voice: new OpenAIVoice(),
});

const { userId, featureFlags } = requestContext.all;

import { createTool } from '@mastra/core/tools';
import { z } from 'zod';

const myTool = createTool({
  id: 'my-tool',
  inputSchema: z.object({ query: z.string() }),
  requestContextSchema: z.object({
    userId: z.string(),
    apiKey: z.string(),
  }),
  execute: async (input, context) => {
    // context.requestContext is typed as RequestContext<{ userId: string, apiKey: string }>
    const userId = context.requestContext?.get('userId');
    return { result: 'success' };
  },
});

import { Agent } from '@mastra/core/agent';
import { z } from 'zod';

const agent = new Agent({
  name: 'my-agent',
  model: openai('gpt-4o'),
  requestContextSchema: z.object({
    userId: z.string(),
    featureFlags: z.object({
      debugMode: z.boolean().optional(),
      enableSearch: z.boolean().optional(),
    }).optional(),
  }),
  instructions: ({ requestContext }) => {
    // Access validated context values with type safety
    const { userId, featureFlags } = requestContext.all;

    const baseInstructions = `You are a helpful assistant. The current user ID is: ${userId}.`;

    if (featureFlags?.debugMode) {
      return `${baseInstructions} Debug mode is enabled - provide verbose responses.`;
    }

    return baseInstructions;
  },
  tools: ({ requestContext }) => {
    const tools: Record<string, any> = {
      weatherInfo,
    };

    // Conditionally add tools based on validated feature flags
    const { featureFlags } = requestContext.all;
    if (featureFlags?.enableSearch) {
      tools['web_search_preview'] = openai.tools.webSearchPreview();
    }

    return tools;
  },
});

import { createWorkflow } from '@mastra/core/workflows';
import { z } from 'zod';

const workflow = createWorkflow({
  id: 'my-workflow',
  inputSchema: z.object({ data: z.string() }),
  requestContextSchema: z.object({
    tenantId: z.string(),
  }),
});

const step = createStep({
  id: 'my-step',
  description: 'My step description',
  inputSchema: z.object({ data: z.string() }),
  outputSchema: z.object({ result: z.string() }),
  requestContextSchema: z.object({
    userId: z.string(),
  }),
  execute: async ({ inputData, requestContext }) => {
    const userId = requestContext?.get('userId');
    return {
      result: 'some result here',
    };
  },
});

workflow.then(step).commit()

const stream = await agent.network(task);

const controller = new AbortController();
const stream = await agent.network(task, {
  abortSignal: controller.signal,
  onAbort: ({ primitiveType, primitiveId }) => {
    logger.info(`Aborted ${primitiveType}:${primitiveId}`);
  },
});

controller.abort();

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:4111' });

// List workspaces and get the first one
const { workspaces } = await client.listWorkspaces();
const workspace = client.getWorkspace(workspaces[0].id);

// Read a file
const { content } = await workspace.readFile('/docs/guide.md');

// List skills
const { skills } = await workspace.listSkills();

// Get skill details
const skill = workspace.getSkill('my-skill');
const details = await skill.details();

// Search content
const { results } = await workspace.search({ query: 'authentication', mode: 'hybrid' });

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

const client = new MastraClient({
  baseUrl: 'http://localhost:3000',
  apiPrefix: '/mastra', // Calls /mastra/agents, /mastra/workflows, etc.
});

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

npx @mastra/codemod@latest v1/workflow-get-init-data .

createStep({
  execute: async ({ getInitData }) => {
    const initData = getInitData();
    if (initData.key === 'value') {}
  },
});

createStep({
  execute: async ({ getInitData }) => {
    const initData = getInitData<any>();
    if (initData.key === 'value') {}
  },
});

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

const server = new MastraServer({
  app,
  mastra,
});
// No way to pass serverless option to MCP HTTP transport

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
});
// MCP HTTP transport now runs in stateless mode

const server = new MastraServer({
  app,
  mastra,
});
// No way to pass serverless option to MCP HTTP transport

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
});
// MCP HTTP transport now runs in stateless mode

const server = new MastraServer({
  app,
  mastra,
});
// No way to pass serverless option to MCP HTTP transport

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
});
// MCP HTTP transport now runs in stateless mode

const server = new MastraServer({
  app,
  mastra,
});
// No way to pass serverless option to MCP HTTP transport

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
});
// MCP HTTP transport now runs in stateless mode

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

// Working memory is loaded but agent cannot update it
const response = await agent.generate("What do you know about me?", {
  memory: {
    thread: "conversation-123",
    resource: "user-alice-456",
    options: { readOnly: true },
  },
});

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

import { FileBrowser, FileViewer, SkillsTable } from '@mastra/playground-ui';

// File browser with navigation
<FileBrowser
  entries={files}
  currentPath="/docs"
  onNavigate={setPath}
  onFileSelect={handleFileSelect}
/>

// Skills table with search
<SkillsTable
  skills={skills}
  onSkillSelect={handleSkillSelect}
/>

import { RecursiveCharacterTransformer, Language } from '@mastra/rag';

// These would all throw "Language X is not supported!" errors
const goTransformer = RecursiveCharacterTransformer.fromLanguage(Language.GO);
const pythonTransformer = RecursiveCharacterTransformer.fromLanguage(Language.PYTHON);
const rustTransformer = RecursiveCharacterTransformer.fromLanguage(Language.RUST);

import { RecursiveCharacterTransformer, Language } from '@mastra/rag';

// All languages now work seamlessly
const goTransformer = RecursiveCharacterTransformer.fromLanguage(Language.GO);
const goChunks = goTransformer.transform(goCodeDocument);

const pythonTransformer = RecursiveCharacterTransformer.fromLanguage(Language.PYTHON);
const pythonChunks = pythonTransformer.transform(pythonCodeDocument);

const rustTransformer = RecursiveCharacterTransformer.fromLanguage(Language.RUST);
const rustChunks = rustTransformer.transform(rustCodeDocument);
// All languages in the Language enum are now fully supported

import { RecursiveCharacterTransformer, Language } from '@mastra/rag';

const transformer = RecursiveCharacterTransformer.fromLanguage(Language.PHP);
const chunks = transformer.transform(phpCodeDocument);
// Throws: "Language PHP is not supported!"

import { RecursiveCharacterTransformer, Language } from '@mastra/rag';

const transformer = RecursiveCharacterTransformer.fromLanguage(Language.PHP);
const chunks = transformer.transform(phpCodeDocument);
// Successfully chunks PHP code at namespace, class, function boundaries

<MastraClientProvider baseUrl="http://localhost:3000">
  {children}
</MastraClientProvider>

<MastraClientProvider baseUrl="http://localhost:3000" apiPrefix="/mastra">
  {children}
</MastraClientProvider>

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

const server = new MastraServer({
  app,
  mastra,
});
// No way to pass serverless option to MCP HTTP transport

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
});
// MCP HTTP transport now runs in stateless mode

// List workspaces
const { workspaces } = await fetch('/api/workspaces').then(r => r.json());
const workspaceId = workspaces[0].id;

// Read a file
const response = await fetch(`/api/workspaces/${workspaceId}/fs/read?path=/docs/guide.md`);
const { content } = await response.json();

// List skills
const skills = await fetch(`/api/workspaces/${workspaceId}/skills`).then(r => r.json());

// Search content
const results = await fetch(`/api/workspaces/${workspaceId}/search?query=authentication&mode=hybrid`)
  .then(r => r.json());

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

# Connect to server using custom prefix
mastra studio --server-port 3000 --server-api-prefix /mastra

More TypeScript Projects

openclaw

developer-roadmap

vue

n8n

More TypeScript Projects

openclaw

developer-roadmap

vue

n8n

Highlights

Unified Workspace API (Filesystem + Sandbox Execution + Search + Skills)

Observability & Streaming Improvements (Trace Status, Better Spans, Tool Approval Tracing)

Server Adapters: Serverless MCP Support + Explicit Route Auth Controls

requestContextSchema: Runtime-Validated, Type-Safe Request Context Everywhere

Breaking Changes

Changelog