Koa Adapter

The @mastra/koa package provides a server adapter for running Mastra with Koa.

info

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

Installation

Install the Koa adapter and Koa framework:

npm install @mastra/koa@latest koa koa-bodyparser

Usage example

server.ts

import Koa from 'koa';
import bodyParser from 'koa-bodyparser';
import { MastraServer } from '@mastra/koa';
import { mastra } from './mastra';

const app = new Koa();
app.use(bodyParser());

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

await server.init();

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Constructor parameters

app:

Koa

Koa 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?:

BodyLimitOptions

Request body size limits

streamOptions?:

StreamOptions

= { redact: true }

Stream redaction config. When true (default), redacts sensitive data (system prompts, tool definitions, API keys) from stream chunks before sending to clients.

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?:

ToolsInput

Available tools for the server

taskStore?:

InMemoryTaskStore

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

Manual initialization

For custom middleware ordering, call each method separately instead of init(). See manual initialization for details.

Examples

• Koa Adapter - Basic Koa server setup

Related

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