MastraServer

Overview

MastraServer provides an HTTP server that exposes your Mastra agents, workflows, and custom APIs. It includes built-in support for Mastra Studio, authentication, CORS, and OpenAPI documentation.

ServerConfig

Configuration interface for the Mastra server.

interface ServerConfig {
  port?: number;
  host?: string;
  studioBase?: string;
  apiPrefix?: string;
  timeout?: number;
  apiRoutes?: ApiRoute[];
  middleware?: Middleware | Middleware[];
  cors?: CorsOptions | false;
  build?: BuildConfig;
  bodySizeLimit?: number;
  auth?: MastraAuthConfig | MastraAuthProvider;
  https?: { key: Buffer; cert: Buffer };
  onError?: (err: Error, c: Context) => Response | Promise<Response>;
}

Configuration Properties

port

number

default:"4111"

Port for the server

host

string

default:"'localhost'"

Host for the server

studioBase

string

default:"'/'"

Base path for Mastra Studio UI

server: {
  studioBase: '/my-mastra-studio'
}

apiPrefix

string

default:"'/api'"

Prefix for API routes

server: {
  apiPrefix: '/mastra'
}

timeout

number

Request timeout in milliseconds

apiRoutes

ApiRoute[]

Custom API routes for the server. See registerApiRoute for creating routes.

middleware

Middleware | Middleware[]

Middleware for the server. Can be a single middleware or an array.

cors

CorsOptions | false

CORS configuration. Set to false to disable CORS.Default configuration:

{
  origin: '*',
  allowMethods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
  allowHeaders: ['Content-Type', 'Authorization', 'x-mastra-client-type'],
  exposeHeaders: ['Content-Length', 'X-Requested-With'],
  credentials: false
}

build

object

Build configuration for the server

Show properties

swaggerUI

boolean

default:"false"

Enable Swagger UI

apiReqLogs

boolean

default:"false"

Enable API request logging

openAPIDocs

boolean

default:"false"

Enable OpenAPI documentation

bodySizeLimit

number

default:"4718592"

Body size limit in bytes (default: 4.5 MB)

auth

MastraAuthConfig | MastraAuthProvider

Authentication configuration for the server

https

{ key: Buffer; cert: Buffer }

HTTPS configuration. Provide key and cert files for running with HTTPS.

onError

(err: Error, c: Context) => Response | Promise<Response>

Custom error handler for unhandled errors. Use this to customize error responses or log errors to external services.

server: {
  onError: (err, c) => {
    // Log to Sentry
    Sentry.captureException(err);
    
    // Return custom response
    return c.json({
      error: err.message,
      timestamp: new Date().toISOString()
    }, 500);
  }
}

registerApiRoute

Function for creating custom API routes.

function registerApiRoute<P extends string>(
  path: P,
  options: RegisterApiRouteOptions<P>
): ApiRoute

path

string

required

URL path for the route. Must not start with /api (reserved for internal routes).

options

RegisterApiRouteOptions

required

Route configuration

Show properties

method

'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'

required

HTTP method for the route

handler

Handler

Route handler function (mutually exclusive with createHandler)

createHandler

(c: Context) => Promise<Handler>

Factory function for creating the handler (mutually exclusive with handler)

openapi

DescribeRouteOptions

OpenAPI documentation for the route

middleware

MiddlewareHandler | MiddlewareHandler[]

Middleware for this specific route

requiresAuth

boolean

default:"true"

Whether this route requires authentication

Example Usage

Basic Server

import { Mastra } from '@mastra/core';

const mastra = new Mastra({
  agents: { /* ... */ },
  server: {
    port: 4111,
    host: 'localhost'
  }
});

Custom API Routes

import { Mastra, registerApiRoute } from '@mastra/core';

const mastra = new Mastra({
  agents: { assistant: myAgent },
  server: {
    port: 4111,
    apiRoutes: [
      registerApiRoute('/hello', {
        method: 'GET',
        handler: async (c) => {
          return c.json({ message: 'Hello, World!' });
        }
      }),
      
      registerApiRoute('/users/:id', {
        method: 'GET',
        handler: async (c) => {
          const id = c.req.param('id');
          const mastra = c.get('mastra');
          const requestContext = c.get('requestContext');
          
          // Use Mastra resources
          const storage = mastra.getStorage();
          // ... fetch user
          
          return c.json({ id, name: 'John Doe' });
        }
      }),
      
      registerApiRoute('/data', {
        method: 'POST',
        handler: async (c) => {
          const body = await c.req.json();
          return c.json({ received: body });
        },
        openapi: {
          summary: 'Submit data',
          description: 'Accepts JSON data',
          requestBody: {
            content: {
              'application/json': {
                schema: {
                  type: 'object',
                  properties: {
                    name: { type: 'string' },
                    value: { type: 'number' }
                  }
                }
              }
            }
          }
        }
      })
    ]
  }
});

Authentication

import { Mastra, defineAuth } from '@mastra/core';

const mastra = new Mastra({
  agents: { /* ... */ },
  server: {
    port: 4111,
    auth: defineAuth({
      protected: [/^\/api\/.*/], // Protect all /api routes
      public: ['/api/health', '/api/status'],
      
      authenticateToken: async (token, request) => {
        // Verify JWT token
        const user = await verifyToken(token);
        return user;
      },
      
      authorize: async (path, method, user, context) => {
        // Check if user has permission
        if (user.role === 'admin') return true;
        if (path.startsWith('/api/public')) return true;
        return false;
      }
    })
  }
});

CORS Configuration

const mastra = new Mastra({
  server: {
    cors: {
      origin: ['https://example.com', 'https://app.example.com'],
      allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
      allowHeaders: ['Content-Type', 'Authorization', 'X-Custom-Header'],
      credentials: true,
      maxAge: 86400
    }
  }
});

// Or disable CORS
const mastra2 = new Mastra({
  server: {
    cors: false
  }
});

Middleware

import { Mastra } from '@mastra/core';

const mastra = new Mastra({
  server: {
    middleware: [
      // Global logging middleware
      async (c, next) => {
        console.log(`${c.req.method} ${c.req.path}`);
        await next();
      },
      
      // Rate limiting middleware
      async (c, next) => {
        const ip = c.req.header('x-forwarded-for') || 'unknown';
        // Check rate limit...
        await next();
      },
      
      // Path-specific middleware
      {
        path: '/api/admin/*',
        handler: async (c, next) => {
          // Admin-only check
          await next();
        }
      }
    ]
  }
});

OpenAPI Documentation

const mastra = new Mastra({
  server: {
    build: {
      openAPIDocs: true,
      swaggerUI: true,
      apiReqLogs: true
    },
    apiRoutes: [
      registerApiRoute('/users', {
        method: 'GET',
        handler: async (c) => {
          return c.json({ users: [] });
        },
        openapi: {
          summary: 'List users',
          description: 'Returns a list of all users',
          responses: {
            200: {
              description: 'Success',
              content: {
                'application/json': {
                  schema: {
                    type: 'object',
                    properties: {
                      users: {
                        type: 'array',
                        items: { type: 'object' }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      })
    ]
  }
});

// Access Swagger UI at: http://localhost:4111/swagger
// Access OpenAPI spec at: http://localhost:4111/openapi.json

Error Handling

import { Mastra } from '@mastra/core';
import * as Sentry from '@sentry/node';

const mastra = new Mastra({
  server: {
    onError: async (err, c) => {
      // Log to Sentry
      Sentry.captureException(err, {
        extra: {
          path: c.req.path,
          method: c.req.method,
          headers: c.req.header()
        }
      });
      
      // Return user-friendly error
      const isDev = process.env.NODE_ENV === 'development';
      return c.json({
        error: isDev ? err.message : 'Internal server error',
        timestamp: new Date().toISOString(),
        requestId: c.req.header('x-request-id')
      }, 500);
    }
  }
});

HTTPS Server

import { readFileSync } from 'fs';
import { Mastra } from '@mastra/core';

const mastra = new Mastra({
  server: {
    port: 443,
    https: {
      key: readFileSync('./key.pem'),
      cert: readFileSync('./cert.pem')
    }
  }
});

Core

Agents

Workflows

Tools

Memory

Storage

Server

Overview

ServerConfig

Configuration Properties

registerApiRoute

Example Usage

Basic Server

Custom API Routes

Authentication

CORS Configuration

Middleware

OpenAPI Documentation

Error Handling

HTTPS Server

Build docs developers (and LLMs) love

Core

Agents

Workflows

Tools

Memory

Storage

Server

Documentation Index

​Overview

​ServerConfig

​Configuration Properties

​registerApiRoute

​Example Usage

​Basic Server

​Custom API Routes

​Authentication

​CORS Configuration

​Middleware

​OpenAPI Documentation

​Error Handling

​HTTPS Server

Build docs developers (and LLMs) love

Overview

ServerConfig

Configuration Properties

registerApiRoute

Example Usage

Basic Server

Custom API Routes

Authentication

CORS Configuration

Middleware

OpenAPI Documentation

Error Handling

HTTPS Server