Express Adapter

The @mastra/express package provides a server adapter for running Mastra with Express.

info

For general adapter concepts (constructor options, initialization flow, etc.), see Server Adapters.

Installation

1. Install the Express adapter and Express framework:

   npm install @mastra/express express

2. Create your server file:

   server.ts

   import express from 'express';
   import { MastraServer } from '@mastra/express';
   import { mastra } from './mastra';
   
   const app = express();
   app.use(express.json()); // Required for body parsing
   
   const server = new MastraServer({ app, mastra });
   await server.init();
   
   app.listen(4111, () => {
     console.log('Server running on port 4111');
   });

note

Express requires express.json() middleware for JSON body parsing. Add it before creating the MastraServer.

Full example

server.ts

import express from 'express';
import { MastraServer } from '@mastra/express';
import { mastra } from './mastra';

const app = express();
app.use(express.json());

const server = new MastraServer({
  app,
  mastra,
  prefix: '/api/v2',
  openapiPath: '/openapi.json',
  bodyLimitOptions: {
    maxSize: 10 * 1024 * 1024, // 10MB
    onError: (err) => ({ error: 'Payload too large', maxSize: '10MB' }),
  },
  streamOptions: { redact: true },
});

await server.init();

app.listen(4111);

Constructor parameters

app:

Application

Express app instance

mastra:

Mastra

Mastra instance

prefix?:

string

= ''

Route path prefix (e.g., `/api/v2`)

openapiPath?:

string

= ''

Path to serve OpenAPI spec (e.g., `/openapi.json`)

bodyLimitOptions?:

{ maxSize: number, onError: (err) => unknown }

Request body size limits

streamOptions?:

{ redact?: boolean }

= { redact: true }

Stream redaction config. When true, redacts sensitive data from streams.

customRouteAuthConfig?:

Map<string, boolean>

Per-route auth overrides. Keys are `METHOD:PATH` (e.g., `GET:/api/health`). Value `false` makes route public, `true` requires auth.

tools?:

Record<string, Tool>

Available tools for the server

taskStore?:

InMemoryTaskStore

Task store for A2A (Agent-to-Agent) operations

Differences from Hono

Aspect	Express	Hono
Body parsing	Requires express.json()	Handled by framework
Context storage	res.locals	c.get() / c.set()
Middleware signature	(req, res, next)	(c, next)
Streaming	res.write() / res.end()	stream() helper
AbortSignal	Created from req.on('close')	c.req.raw.signal

Adding custom routes

Add routes directly to the Express app:

server.ts

const app = express();
app.use(express.json());

const server = new MastraServer({ app, mastra });

// Before init - runs before Mastra middleware
app.get('/early-health', (req, res) => res.json({ status: 'ok' }));

await server.init();

// After init - has access to Mastra context
app.get('/custom', (req, res) => {
  const mastraInstance = res.locals.mastra;
  res.json({ agents: Object.keys(mastraInstance.listAgents()) });
});

app.listen(4111);

tip

Routes added before init() run without Mastra context. Add routes after init() to access the Mastra instance and request context.

Accessing context

In Express middleware and routes, access Mastra context via res.locals:

app.get('/custom', (req, res) => {
  const mastra = res.locals.mastra;
  const requestContext = res.locals.requestContext;
  const abortSignal = res.locals.abortSignal;

  const agent = mastra.getAgent('myAgent');
  res.json({ agent: agent.name });
});

Available properties on res.locals:

Key	Description
mastra	Mastra instance
requestContext	Request context map
abortSignal	Request cancellation signal
tools	Available tools
taskStore	Task store for A2A operations
customRouteAuthConfig	Per-route auth overrides
user	Authenticated user (if auth configured)

Adding middleware

Add Express middleware before or after init():

server.ts

const app = express();
app.use(express.json());

// Middleware before init
app.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
});

const server = new MastraServer({ app, mastra });
await server.init();

// Middleware after init has access to Mastra context
app.use((req, res, next) => {
  const mastra = res.locals.mastra;
  // ...
  next();
});

Manual initialization

For custom middleware ordering, call each method separately instead of init(). See Server Adapters: Manual initialization for details.

Examples

• Express Adapter - Basic Express server setup

Related

• Server Adapters - Shared adapter concepts
• Hono Adapter - Alternative adapter
• MastraServer Reference - Full API reference
• createRoute() Reference - Creating type-safe custom routes