Skip to main content
Mastra provides server adapters for popular Node.js HTTP frameworks. Each adapter implements the same core functionality but integrates seamlessly with its respective framework.

​
Available Adapters

​
Hono Adapter

Lightweight and fast framework with excellent TypeScript support. Installation: 
npm install @mastra/hono hono @hono/node-server
Usage: 
import { Hono } from 'hono';
import { serve } from '@hono/node-server';
import { MastraServer } from '@mastra/hono';
import { Mastra } from '@mastra/core';

const mastra = new Mastra({ /* config */ });

const app = new Hono();

const server = new MastraServer({
  app,
  mastra,
  prefix: '/api',
});

await server.init();

serve({
  fetch: app.fetch,
  port: 3000,
});
Benefits:
  • Minimal overhead
  • Built for edge environments (Cloudflare Workers, Vercel Edge)
  • Excellent TypeScript inference
  • Small bundle size

​
Express Adapter

Mature and widely-used framework with extensive ecosystem. Installation: 
npm install @mastra/express express
Usage: 
import express from 'express';
import { MastraServer } from '@mastra/express';
import { Mastra } from '@mastra/core';

const mastra = new Mastra({ /* config */ });

const app = express();

// Express requires body parsing middleware
app.use(express.json());

const server = new MastraServer({
  app,
  mastra,
  prefix: '/api',
});

await server.init();

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});
Benefits:
  • Large ecosystem of middleware
  • Well-documented and battle-tested
  • Familiar API for many developers
  • Extensive community support

​
Fastify Adapter

High-performance framework focused on speed and low overhead. Installation: 
npm install @mastra/fastify fastify
Usage: 
import Fastify from 'fastify';
import { MastraServer } from '@mastra/fastify';
import { Mastra } from '@mastra/core';

const mastra = new Mastra({ /* config */ });

const app = Fastify({ logger: true });

const server = new MastraServer({
  app,
  mastra,
  prefix: '/api',
});

await server.init();

await app.listen({ port: 3000 });
Benefits:
  • Exceptional performance
  • Built-in validation and serialization
  • Plugin architecture
  • JSON schema support

​
Koa Adapter

Modern framework using async/await and context-based middleware. Installation: 
npm install @mastra/koa koa @koa/router
Usage: 
import Koa from 'koa';
import { bodyParser } from '@koa/bodyparser';
import { MastraServer } from '@mastra/koa';
import { Mastra } from '@mastra/core';

const mastra = new Mastra({ /* config */ });

const app = new Koa();

// Koa requires body parsing middleware
app.use(bodyParser());

const server = new MastraServer({
  app,
  mastra,
  prefix: '/api',
});

await server.init();

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});
Benefits:
  • Clean async/await middleware
  • Lightweight core
  • Context object pattern
  • Good error handling

​
Choosing an Adapter

FrameworkBest ForPerformanceEcosystem Size
HonoEdge/serverless, new projectsExcellentGrowing
ExpressTraditional servers, large teamsGoodVery Large
FastifyHigh-performance APIsExcellentLarge
KoaModern middleware patternsGoodMedium

​
Common Configuration

All adapters support the same configuration options: 
interface MastraServerOptions {
  app: TApp;              // Framework app instance
  mastra: Mastra;         // Mastra instance
  prefix?: string;        // URL prefix (default: '/api')
  openapiPath?: string;   // OpenAPI spec endpoint
  bodyLimitOptions?: {    // Request size limits
    maxSize: number;
    onError: (error: unknown) => unknown;
  };
  streamOptions?: {       // Stream configuration
    redact?: boolean;     // Redact sensitive data
  };
  mcpOptions?: {          // MCP transport options
    serverless?: boolean;
    sessionIdGenerator?: () => string;
  };
}

​
Framework-Specific Features

​
Hono: Edge Runtime Support

Deploy to edge environments: 
// Cloudflare Workers
import { Hono } from 'hono';
import { MastraServer } from '@mastra/hono';

const app = new Hono();
const server = new MastraServer({ app, mastra });
await server.init();

export default app;

​
Express: Middleware Ecosystem

Leverage Express middleware: 
import helmet from 'helmet';
import rateLimit from 'express-rate-limit';

app.use(helmet()); // Security headers

app.use(rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 100,
}));

​
Fastify: Schema Validation

Use Fastify’s built-in schema validation: 
app.addSchema({
  $id: 'customSchema',
  type: 'object',
  properties: {
    userId: { type: 'string' },
  },
});

​
Koa: Context Middleware

Use Koa’s context pattern: 
app.use(async (ctx, next) => {
  ctx.state.requestId = crypto.randomUUID();
  await next();
});

​
Migration Between Adapters

Since all adapters implement the same MastraServer interface, migration is straightforward: 
// Before (Express)
import express from 'express';
import { MastraServer } from '@mastra/express';

const app = express();
app.use(express.json());
const server = new MastraServer({ app, mastra });

// After (Hono)
import { Hono } from 'hono';
import { MastraServer } from '@mastra/hono';

const app = new Hono();
const server = new MastraServer({ app, mastra }); // Same config!
Only framework-specific middleware needs to be updated.

​
Performance Benchmarks

Approximate requests per second (higher is better):
  • Hono: ~50,000 req/s
  • Fastify: ~45,000 req/s
  • Koa: ~35,000 req/s
  • Express: ~30,000 req/s
Benchmarks vary based on hardware, middleware, and workload. Choose based on your specific needs.

​
Next Steps

Creating a Server

Set up your first Mastra server

Middleware

Add authentication and custom middleware

Build docs developers (and LLMs) love

Get started for freeTalk to us