KakaFlow KB

Server overview

6 phút đọc

Server overview

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-11 · Source: crawler_authoritative

Tình huống

Guide for configuring and using the Mastra HTTP server to expose agents, workflows, and custom API endpoints with request routing, middleware, and authentication.

Insight

Mastra runs as an HTTP server built on Hono that exposes agents, workflows, and custom functionality as API endpoints. The server handles request routing, middleware execution, authentication, and streaming responses. Key features include: Middleware for intercepting requests (authentication, logging, CORS, context injection); Custom API Routes for extending the server with HTTP endpoints that access the Mastra instance; Request Context for passing request-specific values to agents, tools, and workflows; Server Adapters for running Mastra with Express, Hono, or custom HTTP servers; Custom Adapters for building adapters for unsupported frameworks; Mastra Client SDK for type-safe client calls; Authentication supporting JWT, Clerk, Supabase, Firebase, Auth0, or WorkOS. The server architecture uses Hono as the underlying framework. When building with mastra build, it generates a Hono-based HTTP server in the .mastra directory. The OpenAI Responses API routes are experimental agent-backed adapters over Mastra agents, memory, and storage—requests run through the selected Mastra agent rather than acting as a raw provider proxy. These routes support streaming, function calling (tools), stored continuations with previous_response_id, conversation threads through conversation_id, provider-specific passthrough with providerOptions, and JSON output through text.format. Stream data redaction is enabled by default and redacts system prompts, tool definitions, API keys, and similar data from streaming chunks. OpenAPI docs and Swagger UI are disabled in production by default but can be enabled via server.build.openAPIDocs and server.build.swaggerUI configuration. TypeScript configuration requires module and moduleResolution settings compatible with modern Node.js; legacy options like CommonJS or node are not supported. Required compilerOptions include target ES2022, module ES2022, moduleResolution bundler, esModuleInterop true, forceConsistentCasingInFileNames true, strict true, skipLibCheck true, noEmit true.

Hành động

Configure the server by passing a server object to the Mastra constructor with port (defaults to PORT env var or 4111) and host (defaults to MASTRA_HOST env var or localhost). Deploy Mastra servers to any Node.js-compatible environment using the Mastra platform or custom infrastructure. Access the OpenAPI specification at http://localhost:4111/api/openapi.json for endpoint documentation and Swagger UI at http://localhost:4111/swagger-ui for interactive testing. Use agent_id with the Responses API to select the handling agent, optionally override the model with the model parameter, and use previous_response_id for stored continuations or conversation_id for conversation threads.

Kết quả

The Mastra server exposes API endpoints for all registered agents and workflows, supports custom API routes and middleware, handles authentication across providers, provides request context for dynamic configuration, and redacts sensitive data from streaming responses by default. OpenAPI and Swagger endpoints are accessible for development but disabled in production by default.

Điều kiện áp dụng

OpenAI Responses API routes are experimental. OpenAPI and Swagger endpoints are disabled in production by default. TypeScript configuration requires ES2022 module and moduleResolution bundler; CommonJS and node resolution are not supported.

Nội dung gốc (Original)

Server overview

Mastra runs as an HTTP server that exposes your agents, workflows, and other functionality as API endpoints. The server handles request routing, middleware execution, authentication, and streaming responses.

Info: This page covers the server configuration options passed to the Mastra constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), visit Server Adapters.

Server features

  • Middleware: Intercept requests for authentication, logging, CORS, or injecting request-specific context.
  • Custom API Routes: Extend the server with your own HTTP endpoints that have access to the Mastra instance.
  • Request Context: Pass request-specific values to agents, tools, and workflows based on runtime conditions.
  • Server Adapters: Run Mastra with Express, Hono, or your own HTTP server instead of the generated server.
  • Custom Adapters: Build adapters for frameworks not officially supported.
  • Mastra Client SDK: Type-safe client for calling agents, workflows, and tools from browser or server environments.
  • Authentication: Secure endpoints with JWT, Clerk, Supabase, Firebase, Auth0, or WorkOS.

Configuration

Configure the server by passing a server object to the Mastra constructor:

import { Mastra } from '@mastra/core'
 
export const mastra = new Mastra({
  server: {
    port: 3000, // Defaults to PORT env var or 4111
    host: '0.0.0.0', // Defaults to MASTRA_HOST env var or 'localhost'
  },
})

Info: Visit the configuration reference for a full list of available server options.

Deploy your server

Mastra servers can be deployed to any Node.js-compatible environment. Deploy it to production using the Mastra platform or your own infastructure. Visit the deployment docs to learn how.

Server architecture

Mastra uses Hono as its underlying HTTP server framework. When you build a Mastra application using mastra build, it generates a Hono-based HTTP server in the .mastra directory.

The server provides:

  • API endpoints for all registered agents and workflows
  • Custom API routes and middleware
  • Authentication across providers
  • Request context for dynamic configuration
  • Stream data redaction for secure responses

REST API

You can explore all available endpoints in the OpenAPI specification at http://localhost:4111/api/openapi.json, which details every endpoint and its request and response schemas.

To explore the API interactively, visit the Swagger UI at http://localhost:4111/swagger-ui. Here, you can discover endpoints and test them directly from your browser.

Note: The OpenAPI and Swagger endpoints are disabled in production by default. To enable them, set server.build.openAPIDocs and server.build.swaggerUI to true respectively.

OpenAI Responses API

Mastra exposes OpenAI-compatible Responses and Conversations routes that let you use Mastra Agents as a Responses API. These routes are agent-backed adapters over Mastra agents, memory, and storage, so requests run through the selected Mastra agent instead of acting as a raw provider proxy.

These APIs are currently experimental.

Use agent_id to select the Mastra agent that should handle the request. Initial requests target an agent directly, and stored follow-up turns can continue with previous_response_id. You can also pass model to override the agent’s configured model for a single request. If you omit model, Mastra uses the model already configured on the agent.

The Responses routes support streaming, function calling (tools), stored continuations with previous_response_id, conversation threads through conversation_id, provider-specific passthrough with providerOptions, and JSON output through text.format.

For the full request and response contract, see the Responses API reference and Conversations API reference. For the complete list of HTTP routes, see server routes.

Stream data redaction

When streaming agent responses, the HTTP layer redacts system prompts, tool definitions, API keys, and similar data from each chunk before sending it to clients. This is enabled by default.

This behavior is only configurable by using server adapters. For server adapters, stream data redaction is enabled by default, too.

TypeScript configuration

Mastra requires module and moduleResolution settings compatible with modern Node.js. Legacy options like CommonJS or node aren’t supported.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

Next steps

Liên kết

Xem thêm:

Sơ đồ

Liên kết ngược