Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mastra-ai/mastra/llms.txt

Use this file to discover all available pages before exploring further.

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