0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/packages/server
History 2026-11-12 21:12:29 +00:00
..
scripts feat(cli): align score and feedback API commands (#30089) 2026-11-11 19:53:52 +01:00
src feat(playground): show the built-in MCP server in Studio (#29932) 2026-11-12 13:40:02 -05:00
.gitignore fix: improve @mastra/server commonjs compatibility (#12068) 2026-01-22 14:35:06 +01:00
AGENTS.md feat(server): add POST /observability/traces/aggregate route (#25501) 2026-09-29 17:10:42 -04:00
CHANGELOG.md chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
CLAUDE.md refactor(server): shared route authorization and in-process dispatchRoute across adapters (#29928) 2026-11-12 12:30:28 -05:00
lint-staged.config.js refactor(lint): replace ESLint with type-aware oxlint (#27476) 2026-10-18 10:38:35 -07:00
oxlint.config.ts chore: migrate linting to oxlint (#20173) 2026-07-25 01:04:02 +02:00
package.json chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
README.md chore: remove stale scripts, workspace entries and package metadata (#29891) 2026-11-10 14:09:52 +01:00
tsconfig.build.json chore: fix go-to-definition using tsc declaration maps (#6089) 2025-07-30 15:41:00 -07:00
tsconfig.json chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
tsdown.config.ts chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
turbo.json chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
vitest.config.ts test: add global test mocks for deterministic UUIDs and silent logging (#13924) 2026-03-09 10:52:47 +01:00

@mastra/server

Typed, framework-agnostic HTTP route definitions, handlers, schemas, and adapter utilities for exposing a Mastra instance over HTTP. This package powers Mastra's development server and the framework-specific server adapters.

Installation

npm install @mastra/server

Usage

The handlers are framework-agnostic functions that accept a Mastra instance and request context. Import them from @mastra/server/handlers, then mount the route handlers under a URL prefix in your web framework:

import { RequestContext } from '@mastra/core/request-context';
import { agents } from '@mastra/server/handlers';
import { Hono } from 'hono';
import { mastra } from './mastra-instance';

const app = new Hono();

app.get('/mastra/agents', async c => {
  const result = await agents.LIST_AGENTS_ROUTE.handler({
    mastra,
    partial: c.req.query('partial'),
    requestContext: new RequestContext(),
  });

  return c.json(result);
});

export default app;

Each exported route combines its HTTP method, path, validation schemas, permission requirements, response type, and handler. Framework adapter packages automate this registration and translate framework requests and responses into the common handler context.

Documentation

Handler groups cover agents and agent controllers, conversations, workflows and dynamic workflows, tools, MCP, memory, vectors, voice, logs, observability, scores, schedules, datasets, processors, workspaces, skills, plans, authentication, A2A tasks, and stored entities.

Route handlers return serializable values or streams and throw HTTPException when an error should map to a non-2xx response. Shared schemas and error-formatting helpers are available through package subpaths for adapters that need to validate requests or emit OpenAPI metadata.

@mastra/server/server-adapter exports the abstract MastraServer contract and common route-registration utilities. Adapter packages implement framework-specific streaming, parameter extraction, response handling, context middleware, authentication middleware, and HTTP logging around this contract.

Changelog

See the package changelog for version history and release notes.

Support

We have an open community Discord. Come and say hello and let us know if you have any questions or need any help getting things running.