Class: MastraServer

@mastra/express subclass that stamps RequestContext with the AppKit user, resource id, and a thread id backed by an HTTP-only session cookie (appkit_<plugin-name>_session_id).

Extends

MastraServer

Constructors

Constructor

new MastraServer(config, …args): MastraServer

Parameters

config

MastraPluginConfig

args

…[{ app: Application; bodyLimitOptions?: BodyLimitOptions; customApiRoutes?: ApiRoute[]; customRouteAuthConfig?: Map<string, boolean>; mastra: Mastra; mcpOptions?: MCPOptions; openapiPath?: string; prefix?: string; streamOptions?: StreamOptions; taskStore?: InMemoryTaskStore; tools?: ToolsInput; }]

Returns

MastraServer

Overrides

ExpressMastraServer.constructor

Properties

bodyLimitOptions?

protected optional bodyLimitOptions?: BodyLimitOptions

Inherited from

ExpressMastraServer.bodyLimitOptions

component

component: RegisteredLogger

Inherited from

ExpressMastraServer.component

customApiRoutes?

protected optional customApiRoutes?: ApiRoute[]

Inherited from

ExpressMastraServer.customApiRoutes

customRouteAuthConfig?

protected optional customRouteAuthConfig?: Map<string, boolean>

Inherited from

ExpressMastraServer.customRouteAuthConfig

httpLoggingConfig?

protected optional httpLoggingConfig?: HttpLoggingConfig

Inherited from

ExpressMastraServer.httpLoggingConfig

logger

protected logger: IMastraLogger

Inherited from

ExpressMastraServer.logger

mastra

protected mastra: Mastra

Inherited from

ExpressMastraServer.mastra

mcpOptions?

protected optional mcpOptions?: MCPOptions

Inherited from

ExpressMastraServer.mcpOptions

name?

optional name?: string

Inherited from

ExpressMastraServer.name

openapiPath?

protected optional openapiPath?: string

Inherited from

ExpressMastraServer.openapiPath

prefix?

protected optional prefix?: string

Inherited from

ExpressMastraServer.prefix

streamOptions

protected streamOptions: StreamOptions

Inherited from

ExpressMastraServer.streamOptions

taskStore?

protected optional taskStore?: InMemoryTaskStore

Inherited from

ExpressMastraServer.taskStore

tools?

protected optional tools?: ToolsInput

Inherited from

ExpressMastraServer.tools

Accessors

app

Get Signature

get protected app(): TApp

Protected getter for subclasses to access the app. This allows subclasses to use this.app naturally.

Returns

TApp

Inherited from

ExpressMastraServer.app

Methods

__setLogger()

__setLogger(logger): void

Set the logger for the agent

Parameters

logger

IMastraLogger

Returns

void

Inherited from

ExpressMastraServer.__setLogger

__setRawConfig()

__setRawConfig(rawConfig): void

Internal

Sets the raw storage configuration for this primitive.

Parameters

rawConfig

Record<string, unknown>

Returns

void

Inherited from

ExpressMastraServer.__setRawConfig

applyRequestMetadataToContext()

protected applyRequestMetadataToContext(__namedParameters): void

Parameters

__namedParameters

getHeader

(name) => string | undefined

requestContext

RequestContext

Returns

void

Inherited from

ExpressMastraServer.applyRequestMetadataToContext

buildCustomRouteHandler()

protected buildCustomRouteHandler(): Promise<boolean>

Creates an internal Hono sub-app with all custom API routes registered. Stores the handler on this instance for use by handleCustomRouteRequest(). Returns true if custom routes were found and registered.

Returns

Promise<boolean>

Inherited from

ExpressMastraServer.buildCustomRouteHandler

checkRouteAuth()

protected checkRouteAuth(route, context): Promise<{ error: string; headers?: Record<string, string>; status: number; } | null>

Check if the current request should be authenticated/authorized. Returns null if auth passes, or an error response if it fails.

This is a thin wrapper around coreAuthMiddleware that:

Routes to the correct auth provider (studio vs server) based on request headers
Handles route-level requiresAuth opt-out (not available in global middleware)
Delegates all other auth logic to coreAuthMiddleware
Translates the AuthResult into the {status, error} format adapters expect

Security: When x-mastra-client-type: studio header is present and studio auth is configured, we ONLY use studio auth. If authentication fails, we return 401 and redirect to login - we do NOT fall back to server auth. This prevents external users from spoofing the studio header to access Studio UI.

Parameters

route

ServerRoute

context

buildAuthorizeContext?

() => unknown

Build framework-specific context for authorize() callback

getHeader

(name) => string | undefined

getQuery

(name) => string | undefined

method

string

path

string

request?

Request

Raw Request object for cookie-based auth providers

requestContext

RequestContext

Returns

Promise<{ error: string; headers?: Record<string, string>; status: number; } | null>

Inherited from

ExpressMastraServer.checkRouteAuth

checkRoutePermission()

protected checkRoutePermission(route, userPermissions, hasPermissionFn, requestContext?): { error: string; message: string; status: number; } | null

Check if the user has the required permission for a route.

Uses convention-based permission derivation:

If route has explicit requiresPermission, use that
Otherwise, derive permission from path/method (e.g., GET /agents → agents:read)
Routes with requiresAuth: false skip permission checks

Permission checks use the RBAC provider that corresponds to the auth mode (studio vs server) that was used for authentication.

Parameters

route

ServerRoute

The route being accessed

userPermissions

string[] | undefined

The user’s permissions from the request context

hasPermissionFn

(userPerms, required) => boolean

Function to check if user permissions match required permission

requestContext?

RequestContext<unknown>

Request context to determine which RBAC provider to use

Returns

{ error: string; message: string; status: number; } | null

Error response if permission denied, null if allowed

Inherited from

ExpressMastraServer.checkRoutePermission

configureMlflowTraceId()

configureMlflowTraceId(res): void

Stamp the turn’s MLflow trace id on the response so the chat client can attach thumbs / comment feedback to it later. MLflow derives its trace id from the OpenTelemetry trace id (tr-<hex>), and every Mastra span for this request inherits the ambient OTel context (see observability.ts), so the active span’s trace id here is the id MLflow will record for the turn.

No-op unless feedback is enabled, and when no live OTel span is active (e.g. the OTLP SDK isn’t registered): in that case the header is simply absent and the client hides feedback for that message, degrading gracefully rather than emitting a bogus trace id.

Parameters

res

Response

Returns

void

configureRequestContextModelOverride()

configureRequestContextModelOverride(req, requestContext): void

Parameters

req

Request

requestContext

RequestContext

Returns

void

configureRequestContextRequestId()

configureRequestContextRequestId(req, res, requestContext): void

Stamp a per-request id and echo it on the response so an upstream proxy / curl client / browser-side log line can pair its view of the request with the matching trace span. Reuses X-Request-Id when the upstream already supplies one so multi-hop traces stay joined; otherwise mints a UUIDv4.

The id is surfaced as mastra__requestId span metadata via TRACE_REQUEST_CONTEXT_KEYS and as the X-Request-Id response header so dev tools can copy it from either side.

Parameters

req

Request

res

Response

requestContext

RequestContext

Returns

void

configureRequestContextScopes()

configureRequestContextScopes(req, requestContext): void

Stamp OAuth scopes from the forwarded access token on MASTRA_SCOPES_KEY for workspace mount gating.

Parameters

req

Request

requestContext

RequestContext

Returns

void

configureRequestContextThreadId()

configureRequestContextThreadId(req, res, requestContext): void

Resolve the thread id this request targets and pin it on RequestContext (consumed by the agent stream for persistence and by the history / threads routes). Resolution order:

A client-supplied thread id (the thread-selection header / ?threadId= query). This is how the chat UI references a specific conversation among the many a user owns - it picks a thread id from the /threads listing (or mints one for a new conversation) and stamps it here. The id is scoped to the caller’s resource by the recall / list routes, so a client can only ever read or write its own threads.
The per-session cookie (appkit_<plugin-name>_session_id), minted on first contact. This is the default single-thread fallback for clients that don’t manage threads explicitly, so existing embeds keep one stable conversation per session with no client changes.

Parameters

req

Request

res

Response

requestContext

RequestContext

Returns

void

configureRequestContextUser()

configureRequestContextUser(req, requestContext): Promise<void>

Parameters

req

Request

requestContext

RequestContext

Returns

Promise<void>

createContextMiddleware()

createContextMiddleware(): (req, res, next) => Promise<void>

Returns

(req, res, next) => Promise<void>

Inherited from

ExpressMastraServer.createContextMiddleware

getApp()

getApp<T>(): T

Get the app instance.

Returns the server app that was passed to the constructor. This allows users to access the underlying server framework’s app for direct operations like calling routes via app.fetch() (Hono) or using the app for testing.

Type Parameters

T

T = Application

The expected type of the app (defaults to TApp)

Returns

T

The app instance cast to T. Callers are responsible for ensuring T matches the actual app type.

Example

const app = adapter.getApp<Hono>();
const response = await app.fetch(new Request('http://localhost/api/agents'));

Inherited from

ExpressMastraServer.getApp

getEffectiveAuthConfig()

protected getEffectiveAuthConfig(getHeader): { authConfig: unknown; authMode: MastraAuthMode; } | null

Determines which auth configuration to use for the current request.

Request routing logic:

If x-mastra-client-type: studio header is present AND studio.auth is configured: → Use studio auth (for internal team members accessing Studio UI)
If studio header is present but studio.auth is NOT configured: → No auth required (Studio development mode)
Otherwise: → Use server auth (for external customers calling API)

Security note: The header is only for routing - auth validation happens via session cookies/tokens. If someone spoofs the studio header but doesn’t have a valid studio session, they’ll get a 401 (not fall back to server auth).

Parameters

getHeader

(name) => string | undefined

Returns

{ authConfig: unknown; authMode: MastraAuthMode; } | null

Inherited from

ExpressMastraServer.getEffectiveAuthConfig

getEffectiveFGAProvider()

protected getEffectiveFGAProvider(requestContext): IFGAProvider<any> | undefined

Gets the effective FGA provider for the current request based on auth mode.

Parameters

requestContext

RequestContext

Returns

IFGAProvider<any> | undefined

Inherited from

ExpressMastraServer.getEffectiveFGAProvider

getEffectiveRBACProvider()

protected getEffectiveRBACProvider(requestContext): IRBACProvider<any> | undefined

Gets the effective RBAC provider for the current request based on auth mode.

Parameters

requestContext

RequestContext

Returns

IRBACProvider<any> | undefined

Inherited from

ExpressMastraServer.getEffectiveRBACProvider

getParams()

getParams(route, request): Promise<ParsedRequestParams>

Parameters

route

ServerRoute

request

Request

Returns

Promise<ParsedRequestParams>

Inherited from

ExpressMastraServer.getParams

handleCustomRouteRequest()

protected handleCustomRouteRequest(url, method, headers, body, requestContext?, signal?): Promise<Response | null>

Forwards a request to the internal custom route handler. Returns the Response if a custom route matched, or null to fall through.

Parameters

url

string

method

string

headers

Record<string, string | string[] | undefined>

body

unknown

requestContext?

RequestContext<unknown>

signal?

AbortSignal

Returns

Promise<Response | null>

Inherited from

ExpressMastraServer.handleCustomRouteRequest

init()

init(): Promise<void>

Returns

Promise<void>

Inherited from

ExpressMastraServer.init

mergeRequestContext()

protected mergeRequestContext(__namedParameters): RequestContext

Parameters

__namedParameters

bodyRequestContext?

Record<string, any>

paramsRequestContext?

Record<string, any>

Returns

RequestContext

Inherited from

ExpressMastraServer.mergeRequestContext

parseBody()

parseBody(route, body): Promise<unknown>

Parameters

route

ServerRoute

body

unknown

Returns

Promise<unknown>

Inherited from

ExpressMastraServer.parseBody

parsePathParams()

parsePathParams(route, params): Promise<Record<string, any>>

Parameters

route

ServerRoute

params

Record<string, string>

Returns

Promise<Record<string, any>>

Inherited from

ExpressMastraServer.parsePathParams

parseQueryParams()

parseQueryParams(route, params): Promise<Record<string, any>>

Parameters

route

ServerRoute

params

Record<string, QueryParamValue>

Returns

Promise<Record<string, any>>

Inherited from

ExpressMastraServer.parseQueryParams

registerAuthMiddleware()

registerAuthMiddleware(): void

Returns

void

Overrides

ExpressMastraServer.registerAuthMiddleware

registerContextMiddleware()

registerContextMiddleware(): void

Returns

void

Inherited from

ExpressMastraServer.registerContextMiddleware

registerCustomApiRoutes()

registerCustomApiRoutes(): Promise<void>

Override in adapters to register custom API routes defined via registerApiRoute(). Called by init() between registerAuthMiddleware() and registerRoutes().

Returns

Promise<void>

Inherited from

ExpressMastraServer.registerCustomApiRoutes

registerHttpLoggingMiddleware()

registerHttpLoggingMiddleware(): void

Returns

void

Inherited from

ExpressMastraServer.registerHttpLoggingMiddleware

registerOpenAPIRoute()

registerOpenAPIRoute(app, config, __namedParameters): Promise<void>

Parameters

app

Application

config

OpenAPIConfig | undefined

__namedParameters

prefix?

string

Returns

Promise<void>

Inherited from

ExpressMastraServer.registerOpenAPIRoute

registerRoute()

registerRoute(app, route, __namedParameters?): Promise<void>

Parameters

app

Application

route

ServerRoute

__namedParameters?

prefix?

string

Returns

Promise<void>

Inherited from

ExpressMastraServer.registerRoute

registerRoutes()

registerRoutes(): Promise<void>

Returns

Promise<void>

Inherited from

ExpressMastraServer.registerRoutes

resolveValidationError()

protected resolveValidationError(route, error, context): ValidationErrorResponse

Parameters

route

ServerRoute

error

ZodError

context

ValidationErrorContext

Returns

ValidationErrorResponse

Inherited from

ExpressMastraServer.resolveValidationError

sendResponse()

sendResponse(route, response, result, request?, prefix?): Promise<void>

Parameters

route

ServerRoute

response

Response

result

unknown

request?

Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>

prefix?

string

Returns

Promise<void>

Inherited from

ExpressMastraServer.sendResponse

shouldLogRequest()

protected shouldLogRequest(path): boolean

Determines if a request to the given path should be logged.

Parameters

path

string

The request path to check

Returns

boolean

true if the request should be logged, false otherwise

Inherited from

ExpressMastraServer.shouldLogRequest

stream()

stream(route, res, result): Promise<void>

Parameters

route

ServerRoute

res

Response

result

fullStream

ReadableStream

Returns

Promise<void>

Inherited from

ExpressMastraServer.stream

toRawConfig()

toRawConfig(): Record<string, unknown> | undefined

Returns the raw storage configuration this primitive was created from, or undefined if it was created from code.

Returns

Record<string, unknown> | undefined

Inherited from

ExpressMastraServer.toRawConfig

validateAgentBuilderLicense()

validateAgentBuilderLicense(): Promise<void>

Validate that an Agent Builder configuration has a valid EE license. Throws if the editor is configured with builder support but no valid EE license is available.

Returns

Promise<void>

Inherited from

ExpressMastraServer.validateAgentBuilderLicense

validateCustomRoutePaths()

protected validateCustomRoutePaths(routes): void

Validates that no custom route path collides with the built-in route prefix. Throws if any route path starts with the server’s apiPrefix.

Parameters

routes

ApiRoute[]

Returns

void

Inherited from

ExpressMastraServer.validateCustomRoutePaths

validateEELicense()

validateEELicense(): Promise<void>

Validate that EE features have a valid license in production. Throws if RBAC or FGA is configured without a valid license outside dev/test environments.

Returns

Promise<void>

Inherited from

ExpressMastraServer.validateEELicense

validateFGAPolicyCoverage()

validateFGAPolicyCoverage(): Promise<void>

Validate route-level FGA policy coverage when an FGA provider opts into startup checks.

Returns

Promise<void>

Inherited from

ExpressMastraServer.validateFGAPolicyCoverage

writeCustomRouteResponse()

protected writeCustomRouteResponse(response, nodeRes, signal?): Promise<void>

Pipes a custom route Response to a Node.js ServerResponse (http.ServerResponse). Works with Koa (ctx.res), Express (res), and Fastify (reply.raw).

Parameters

response

Response

nodeRes

object & WritableStream

signal?

AbortSignal

Returns

Promise<void>

Inherited from

ExpressMastraServer.writeCustomRouteResponse