MastraServer

The MastraServer abstract class is the base for all server adapters. Extend this class to create adapters for frameworks other than Hono or Express.

Import

import { MastraServer } from '@mastra/server/server-adapter';

Type parameters

MastraServer<TApp, TRequest, TResponse>

Parameter	Description
TApp	Framework app type (e.g., Hono, Application)
TRequest	Framework request type
TResponse	Framework response/context type

Constructor

constructor(options: MastraServerOptions<TApp>)

Options

app:

TApp

Framework app instance

mastra:

Mastra

Mastra instance

prefix?:

string

= ''

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

openapiPath?:

string

= ''

Path to serve OpenAPI spec

bodyLimitOptions?:

BodyLimitOptions

Request body size limits

streamOptions?:

StreamOptions

= { redact: true }

Stream redaction config

customRouteAuthConfig?:

Map<string, boolean>

Per-route auth overrides

tools?:

Record<string, Tool>

Available tools for the server

taskStore?:

InMemoryTaskStore

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

playground?:

boolean

= false

Can be read to set context values in adapters implementing the MastraServer

isDev?:

boolean

= false

Development mode flag

Abstract methods

These methods must be implemented by adapters:

registerContextMiddleware()

Attach Mastra context to every request.

abstract registerContextMiddleware(): void

Context to attach:

• mastra - Mastra instance
• requestContext - Request-scoped context
• tools - Available tools
• abortSignal - Request cancellation signal

registerAuthMiddleware()

Register authentication and authorization middleware.

abstract registerAuthMiddleware(): void

registerRoute()

Register a single route with the framework.

abstract registerRoute(
  app: TApp,
  route: ServerRoute,
  options: { prefix?: string }
): Promise<void>

getParams()

Extract parameters from the request.

abstract getParams(
  route: ServerRoute,
  request: TRequest
): Promise<{
  urlParams: Record<string, string>;
  queryParams: Record<string, string>;
  body: unknown;
}>

sendResponse()

Send response based on route type.

abstract sendResponse(
  route: ServerRoute,
  response: TResponse,
  result: unknown
): Promise<unknown>

stream()

Handle streaming responses.

abstract stream(
  route: ServerRoute,
  response: TResponse,
  result: unknown
): Promise<unknown>

Instance methods

init()

Initialize the server by registering all middleware and routes.

async init(): Promise<void>

Calls in order:

1. registerContextMiddleware()
2. registerAuthMiddleware()
3. registerRoutes()

registerRoutes()

Register all Mastra routes.

async registerRoutes(): Promise<void>

getApp()

Get the framework app instance.

getApp<T = TApp>(): T

parsePathParams()

Validate path parameters with the route's Zod schema.

async parsePathParams(
  route: ServerRoute,
  params: Record<string, string>
): Promise<Record<string, unknown>>

parseQueryParams()

Validate query parameters with the route's Zod schema.

async parseQueryParams(
  route: ServerRoute,
  params: Record<string, string>
): Promise<Record<string, unknown>>

parseBody()

Validate request body with the route's Zod schema.

async parseBody(
  route: ServerRoute,
  body: unknown
): Promise<unknown>

registerOpenAPIRoute()

Register an endpoint that serves the OpenAPI specification.

async registerOpenAPIRoute(
  app: TApp,
  config: OpenAPIConfig,
  options: { prefix?: string }
): Promise<void>

Protected methods

mergeRequestContext()

Merge request context from multiple sources (query params and body).

protected mergeRequestContext(options: {
  paramsRequestContext?: Record<string, any>;
  bodyRequestContext?: Record<string, any>;
}): RequestContext

Types

BodyLimitOptions

interface BodyLimitOptions {
  maxSize: number;
  onError: (error: unknown) => unknown;
}

StreamOptions

interface StreamOptions {
  redact?: boolean;
}

Example

import { MastraServer, ServerRoute } from '@mastra/server/server-adapter';
import type { Mastra } from '@mastra/core';

export class MyServer extends MastraServer<MyApp, MyRequest, MyResponse> {
  registerContextMiddleware(): void {
    this.app.use('*', (req, res, next) => {
      res.locals.mastra = this.mastra;
      next();
    });
  }

  registerAuthMiddleware(): void {
    const auth = this.mastra.getServer()?.auth;
    if (!auth) return;
    // Implement auth
  }

  async registerRoute(app, route, { prefix }) {
    // Implement route registration
  }

  async getParams(route, request) {
    return {
      urlParams: request.params,
      queryParams: request.query,
      body: request.body,
    };
  }

  async sendResponse(route, response, result) {
    return response.json(result);
  }

  async stream(route, response, result) {
    // Implement streaming
  }
}

Related

• Server Adapters - Using adapters
• Custom Adapters - Creating custom adapters
• createRoute() - Creating custom routes