Skip to main content
The Mastra server package provides typed HTTP handlers and server adapters to expose your Mastra instance over HTTP. This enables you to:
  • Create REST and streaming endpoints for agents and workflows
  • Access telemetry and observability data via HTTP
  • Run the Mastra development UI with mastra dev
  • Deploy your agents as production-ready HTTP services

​
Package Architecture

The server package consists of two main components:

​
Handlers

Framework-agnostic handler functions that accept a Mastra instance and request context. These are exported from @mastra/server/handlers and include:
  • agents - List agents, retrieve metadata, and run generate or stream
  • workflows - Start and inspect workflow runs
  • tools - Discover available tools
  • memory - Interact with memory stores
  • logs - Query runtime logs
  • observability - Expose telemetry metrics
  • vectors - Vector store operations
  • voice - Voice synthesis endpoints

​
Server Adapters

Framework-specific implementations that integrate handlers with popular HTTP frameworks:
  • @mastra/hono - Hono adapter
  • @mastra/express - Express adapter
  • @mastra/koa - Koa adapter
  • @mastra/fastify - Fastify adapter

​
Installation

Install the server package and your preferred adapter: 
npm install @mastra/server @mastra/hono
# or
npm install @mastra/server @mastra/express

​
Quick Start

Here’s a minimal example using the Hono adapter: 
import { Mastra } from '@mastra/core';
import { MastraServer } from '@mastra/hono';
import { Hono } from 'hono';
import { serve } from '@hono/node-server';

const mastra = new Mastra({
  agents: { /* your agents */ },
  workflows: { /* your workflows */ },
});

const app = new Hono();

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

await server.init();

serve({
  fetch: app.fetch,
  port: 3000,
});

console.log('Server running on http://localhost:3000');
The server will automatically register routes for all handlers at the specified prefix:
  • GET /api/agents - List all agents
  • POST /api/agents/:agentId/generate - Generate agent response
  • POST /api/agents/:agentId/stream - Stream agent response
  • POST /api/workflows/:workflowId/execute - Execute workflow
  • And many more…

​
Server Configuration

The MastraServer constructor accepts these options: 
interface MastraServerOptions {
  app: TApp;              // Your HTTP framework app instance
  mastra: Mastra;         // Your Mastra instance
  prefix?: string;        // URL prefix for all routes (default: '/api')
  openapiPath?: string;   // Path for OpenAPI spec endpoint
  bodyLimitOptions?: {    // Request body size limits
    maxSize: number;
    onError: (error: unknown) => unknown;
  };
  streamOptions?: {       // Stream response configuration
    redact?: boolean;     // Redact sensitive data (default: true)
  };
  mcpOptions?: {          // MCP transport options
    serverless?: boolean; // Stateless mode for serverless environments
    sessionIdGenerator?: () => string;
  };
}

​
Running the Development UI

The mastra dev CLI command starts a local development server with a web UI: 
mastra dev
This launches a server at http://localhost:3000 using the handlers from this package, providing a visual interface to:
  • Test agents interactively
  • Execute workflows
  • View logs and telemetry
  • Explore available tools

​
Next Steps

Creating a Server

Learn how to set up an HTTP server for your agents

Routes & Handlers

Understand the available routes and handlers

Server Adapters

Choose and configure a server adapter

Middleware

Add authentication and custom middleware

Build docs developers (and LLMs) love

Get started for freeTalk to us