Skip to main content
This guide walks through creating a production-ready HTTP server for your Mastra agents and workflows.

​
Basic Server Setup

First, install the server package and your preferred adapter: 
npm install @mastra/server @mastra/hono hono @hono/node-server
Create a server file that initializes your Mastra instance and server:
server.ts
import { Mastra } from '@mastra/core';
import { MastraServer } from '@mastra/hono';
import { Hono } from 'hono';
import { serve } from '@hono/node-server';

// Initialize your Mastra instance
const mastra = new Mastra({
  agents: {
    myAgent: {
      name: 'My Agent',
      instructions: 'You are a helpful assistant',
      model: 'gpt-4',
    },
  },
});

// Create HTTP app
const app = new Hono();

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

// Register all routes
await server.init();

// Start the server
serve({
  fetch: app.fetch,
  port: 3000,
});

console.log('Server running on http://localhost:3000');

​
Server Configuration Options

​
URL Prefix

All routes are mounted under a configurable prefix: 
const server = new MastraServer({
  app,
  mastra,
  prefix: '/api/v1', // Routes will be /api/v1/agents, /api/v1/workflows, etc.
});

​
Body Size Limits

Configure maximum request body size: 
const server = new MastraServer({
  app,
  mastra,
  bodyLimitOptions: {
    maxSize: 10 * 1024 * 1024, // 10MB
    onError: (error) => ({
      error: 'Request too large',
      maxSize: '10MB',
    }),
  },
});

​
Stream Options

Control sensitive data redaction in streaming responses: 
const server = new MastraServer({
  app,
  mastra,
  streamOptions: {
    redact: true, // Default: true - redacts system prompts, tool definitions, API keys
  },
});
Set redact: false only in development or for internal services that require full request data.

​
MCP Transport Options

Configure Model Context Protocol transport for serverless environments: 
const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true, // Run without session management
    sessionIdGenerator: () => crypto.randomUUID(),
  },
});

​
OpenAPI Documentation

Expose an OpenAPI specification for your server: 
const server = new MastraServer({
  app,
  mastra,
  openapiPath: '/openapi.json',
});

await server.init();

// OpenAPI spec available at http://localhost:3000/api/openapi.json

​
Express Adapter Example

Using Express instead of Hono: 
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');
});

​
Testing Your Server

Once your server is running, test the endpoints: 
# List available agents
curl http://localhost:3000/api/agents

# Generate agent response
curl -X POST http://localhost:3000/api/agents/myAgent/generate \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'

# Stream agent response
curl -X POST http://localhost:3000/api/agents/myAgent/stream \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'

​
Production Considerations

​
Environment Variables

Store configuration in environment variables: 
const PORT = process.env.PORT || 3000;
const API_PREFIX = process.env.API_PREFIX || '/api';

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

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

​
Error Handling

The server automatically handles errors and returns appropriate HTTP status codes:
  • 400 - Invalid request (validation errors)
  • 401 - Authentication required
  • 403 - Access denied
  • 413 - Request too large
  • 500 - Internal server error

​
Request Context

Pass request-scoped data using requestContext: 
// Client sends request context
fetch('/api/agents/myAgent/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'Hello' }],
    requestContext: {
      userId: '123',
      sessionId: 'abc',
    },
  }),
});
This context is available in your agent code via the RequestContext API.

​
Next Steps

Routes & Handlers

Explore available routes and handlers

Middleware

Add authentication and custom middleware

Build docs developers (and LLMs) love

Get started for freeTalk to us