# 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

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

## Type parameters

```typescript
MastraServer<TApp, TRequest, TResponse>
```

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

## Constructor

```typescript
constructor(options: MastraServerOptions<TApp>)
```

### Options

**app:** (`TApp`): Framework app instance

**mastra:** (`Mastra`): Mastra instance

**prefix?:** (`string`): Route path prefix (e.g., \`/api/v2\`) (Default: `''`)

**openapiPath?:** (`string`): Path to serve OpenAPI spec (Default: `''`)

**bodyLimitOptions?:** (`BodyLimitOptions`): Request body size limits

**streamOptions?:** (`StreamOptions`): Stream redaction config (Default: `{ redact: true }`)

**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

**mcpOptions?:** (`MCPOptions`): MCP transport options for serverless environments

## Abstract methods

These methods must be implemented by adapters:

### registerContextMiddleware()

Attach Mastra context to every request.

```typescript
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.

```typescript
abstract registerAuthMiddleware(): void
```

### registerRoute()

Register a single route with the framework.

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

### getParams()

Extract parameters from the request.

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

### sendResponse()

Send response based on route type.

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

### stream()

Handle streaming responses.

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

## Instance methods

### init()

Initialize the server by registering all middleware and routes.

```typescript
async init(): Promise<void>
```

Calls in order:

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

### registerRoutes()

Register all Mastra routes.

```typescript
async registerRoutes(): Promise<void>
```

### getApp()

Get the framework app instance.

```typescript
getApp<T = TApp>(): T
```

### parsePathParams()

Validate path parameters with the route's Zod schema.

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

### parseQueryParams()

Validate query parameters with the route's Zod schema.

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

### parseBody()

Validate request body with the route's Zod schema.

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

### registerOpenAPIRoute()

Register an endpoint that serves the OpenAPI specification.

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

## Protected methods

### mergeRequestContext()

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

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

## Types

### BodyLimitOptions

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

### StreamOptions

```typescript
interface StreamOptions {
  redact?: boolean;
}
```

### MCPOptions

```typescript
interface MCPOptions {
  serverless?: boolean;
  sessionIdGenerator?: () => string;
}
```

| Property             | Description                                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `serverless`         | When `true`, runs MCP in stateless mode without session management. Use for serverless environments like Cloudflare Workers or Vercel Edge. |
| `sessionIdGenerator` | Custom function to generate session IDs.                                                                                                    |

## Example

```typescript
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](https://mastra.ai/docs/server/server-adapters) - Using adapters
- [Custom Adapters](https://mastra.ai/docs/server/custom-adapters) - Creating custom adapters
- [createRoute()](https://mastra.ai/reference/server/create-route) - Creating custom routes