Adaptateurs de serveur

Les adaptateurs de serveur vous permettent d’exécuter Mastra avec votre propre serveur HTTP plutôt qu’avec le serveur Hono généré par mastra build. Ils offrent un contrôle accru sur la configuration du serveur, notamment l’ordre des middlewares personnalisés, l’authentification, la journalisation et la configuration du déploiement. Vous pouvez ainsi intégrer Mastra à n’importe quelle application Node.js sans modifier la façon dont les agents ou les workflows s’exécutent.

attention

Les adaptateurs de serveur utilisent l’instance mastra que vous leur transmettez et n’effectuent pas de découverte fondée sur les fichiers. Enregistrez les agents sur cette instance dans le code. Pour utiliser des agents définis dans des fichiers, exécutez Mastra en tant que serveur distinct avec mastra dev ou mastra build.

Quand utiliser les adaptateurs de serveur

• Vous souhaitez ajouter automatiquement les endpoints de Mastra à une application existante
• Vous avez besoin d’un accès direct à l’instance du serveur pour une configuration personnalisée
• Votre équipe préfère utiliser un autre framework de serveur plutôt que le serveur Hono créé par mastra build.

astuce

Pour les déploiements ne nécessitant aucune personnalisation du serveur, utilisez plutôt mastra build. Cette commande configure le serveur, enregistre les middlewares et applique les paramètres de déploiement en fonction de la configuration de votre projet. Consultez la page Configuration du serveur.

Si vous souhaitez utiliser Studio avec votre adaptateur de serveur, utilisez mastra studio pour lancer uniquement l’interface utilisateur de Studio.

Adaptateurs disponibles

Mastra fournit actuellement les adaptateurs de serveur officiels suivants :

• @mastra/express
• @mastra/hono
• @mastra/fastify
• @mastra/koa
• @mastra/nestjs

Vous pouvez créer votre propre adaptateur. Pour en savoir plus, consultez la page Adaptateurs personnalisés.

Installation

Installez l’adaptateur correspondant au framework de votre choix.

Express

npm

npm install @mastra/express@latest

pnpm

pnpm add @mastra/express@latest

Yarn

yarn add @mastra/express@latest

Bun

bun add @mastra/express@latest

Hono

npm

npm install @mastra/hono@latest

pnpm

pnpm add @mastra/hono@latest

Yarn

yarn add @mastra/hono@latest

Bun

bun add @mastra/hono@latest

Fastify

npm

npm install @mastra/fastify@latest

pnpm

pnpm add @mastra/fastify@latest

Yarn

yarn add @mastra/fastify@latest

Bun

bun add @mastra/fastify@latest

Koa

npm

npm install @mastra/koa@latest

pnpm

pnpm add @mastra/koa@latest

Yarn

yarn add @mastra/koa@latest

Bun

bun add @mastra/koa@latest

NestJS

npm

npm install @mastra/nestjs@latest

pnpm

pnpm add @mastra/nestjs@latest

Yarn

yarn add @mastra/nestjs@latest

Bun

bun add @mastra/nestjs@latest

Configuration

Initialisez votre application comme d’habitude, puis créez un MastraServer en lui transmettant l’app et votre instance mastra principale provenant de src/mastra/index.ts. L’appel à init() enregistre automatiquement les middlewares Mastra et tous les endpoints disponibles. Vous pouvez continuer à ajouter vos propres routes normalement, avant ou après init() ; elles s’exécuteront aux côtés des endpoints de Mastra.

Express

src/express-server.ts

import express from 'express'
import { MastraServer } from '@mastra/express'
import { mastra } from './mastra'

const app = express()
app.use(express.json())

const server = new MastraServer({ app, mastra })

await server.init()

app.listen(4111, () => {
  console.log('Server running on port 4111')
})

Consultez la documentation de l’adaptateur Express pour connaître toutes les options de configuration.

Hono

src/hono-server.ts

import { Hono } from 'hono'
import { serve } from '@hono/node-server'
import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'
import { mastra } from './mastra'

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()

const server = new MastraServer({ app, mastra })

await server.init()

serve({ fetch: app.fetch, port: 4111 }, () => {
  console.log('Server running on port 4111')
})

Consultez la documentation de l’adaptateur Hono pour connaître toutes les options de configuration.

Fastify

src/fastify-server.ts

import Fastify from 'fastify'
import { MastraServer } from '@mastra/fastify'
import { mastra } from './mastra'

const app = Fastify()
const server = new MastraServer({ app, mastra })

await server.init()

app.get('/health', async request => {
  const mastraInstance = request.mastra
  const agents = Object.keys(mastraInstance.listAgents())
  return { status: 'ok', agents }
})

const port = 4111

app.listen({ port }, () => {
  console.log(`Server running on http://localhost:${port}`)
  console.log(`Try: curl http://localhost:${port}/api/agents`)
})

Consultez la documentation de l’adaptateur Fastify pour connaître toutes les options de configuration.

Koa

src/koa-server.ts

import Koa from 'koa'
import bodyParser from 'koa-bodyparser'
import { MastraServer } from '@mastra/koa'
import { mastra } from './mastra'

const app = new Koa()
app.use(bodyParser()) // Required for body parsing

const server = new MastraServer({ app, mastra })

await server.init()

app.use(async (ctx, next) => {
  if (ctx.path === '/health' && ctx.method === 'GET') {
    const mastraInstance = ctx.state.mastra
    const agents = Object.keys(mastraInstance.listAgents())
    ctx.body = { status: 'ok', agents }
    return
  }
  await next()
})

const port = 4111

app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`)
  console.log(`Try: curl http://localhost:${port}/api/agents`)
})

Consultez la documentation de l’adaptateur Koa pour connaître toutes les options de configuration.

NestJS

src/app.module.ts

import { Module } from '@nestjs/common'
import { MastraModule } from '@mastra/nestjs'
import { mastra } from './mastra'

@Module({
  imports: [
    MastraModule.register({
      mastra,
    }),
  ],
})
export class AppModule {}

src/main.ts

import { NestFactory } from '@nestjs/core'
import { AppModule } from './app.module'

async function bootstrap() {
  const app = await NestFactory.create(AppModule)
  await app.listen(3000)
}

bootstrap()

Consultez la documentation de l’adaptateur NestJS pour connaître toutes les options de configuration.

Déroulement de l’initialisation

L’appel à init() exécute trois étapes dans l’ordre. Comprendre ce déroulement vous aide lorsque vous devez insérer votre propre middleware à des endroits précis.

1. registerContextMiddleware() : associe l’instance Mastra, le contexte de requête, les tools et le signal d’abandon à chaque requête. Mastra devient ainsi accessible à tous les middlewares et gestionnaires de routes suivants.
2. registerAuthMiddleware() : exécute la fonction d’authentification de l’adaptateur pendant l’initialisation. Les adaptateurs officiels appliquent l’authentification directement lorsque Mastra enregistre les routes intégrées et les routes registerApiRoute(). Les routes ajoutées directement au framework doivent donc utiliser la fonction utilitaire createAuthMiddleware() exportée par l’adaptateur lorsqu’elles nécessitent l’authentification Mastra.
3. registerRoutes() : enregistre toutes les routes de l’API Mastra pour les agents, les workflows et les autres fonctionnalités. Enregistre également les routes MCP si des serveurs MCP sont configurés.

Initialisation manuelle

Pour personnaliser l’ordre des middlewares, appelez chaque méthode séparément au lieu d’utiliser init(). Cette approche est utile lorsqu’un middleware doit s’exécuter avant la mise en place du contexte Mastra, ou lorsque vous devez insérer une logique entre les étapes d’initialisation.

server.ts

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

// Your middleware first
app.use(loggingMiddleware);

server.registerContextMiddleware();

// Middleware that needs Mastra context
app.use(customMiddleware);

await server.registerRoutes();

// Routes after Mastra
app.get('/health', ...);

astuce

Utilisez l’initialisation manuelle lorsqu’un middleware doit s’exécuter avant que le contexte Mastra soit disponible, ou lorsque vous devez insérer un middleware entre les étapes de mise en place du contexte et d’authentification.

Ajout de routes personnalisées

Vous pouvez ajouter vos propres routes à l’application aux côtés de celles de Mastra.

• Les routes ajoutées avant init() n’ont pas accès au contexte Mastra.
• Les routes ajoutées après init() ont accès au contexte Mastra (l’instance Mastra, le contexte de requête, l’utilisateur authentifié, etc.).
• Si vous souhaitez que Mastra gère l’authentification et les métadonnées de route telles que requiresAuth, privilégiez registerApiRoute().
• Lorsque vous montez des routes directement sur l’application du framework, utilisez la fonction utilitaire createAuthMiddleware() exportée par l’adaptateur si ces routes nécessitent l’authentification Mastra.

Pour en savoir plus, consultez la section « Ajout de routes personnalisées » pour Express et Hono.

Préfixes de route

Par défaut, les routes Mastra sont enregistrées sous /api/agents, /api/workflows, etc. Utilisez l’option prefix pour modifier ce préfixe. Cela s’avère utile pour le versionnement d’une API ou lors de l’intégration à une application existante qui possède ses propres routes /api.

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

Avec ce préfixe, les routes Mastra deviennent /api/v2/agents, /api/v2/workflows, etc. Les routes personnalisées que vous ajoutez directement à l’application ne sont pas affectées par ce préfixe.

Spécification OpenAPI

Mastra peut générer une spécification OpenAPI pour toutes les routes enregistrées. Celle-ci est utile pour la documentation, la génération de clients ou l’intégration avec des outils d’API. Activez-la en définissant l’option openapiPath :

const server = new MastraServer({
  app,
  mastra,
  openapiPath: '/openapi.json',
})

La spécification est générée à partir des schémas Zod définis sur chaque route et servie au chemin indiqué. Elle inclut toutes les routes Mastra ainsi que les routes personnalisées créées avec createRoute().

Masquage des données de stream

Lors du streaming de réponses d’agents via HTTP, la couche de streaming HTTP masque les informations sensibles dans les chunks du stream avant de les envoyer aux clients. Cela évite l’exposition accidentelle des éléments suivants :

• Prompts système et instructions des agents
• Définitions des tools et leurs paramètres
• Clés d’API et autres identifiants présents dans les corps de requête
• Données de configuration internes

Ce masquage intervient à la limite HTTP. Les fonctions de rappel internes telles que onStepFinish conservent donc l’accès à l’ensemble des données de la requête à des fins de débogage et d’observabilité.

Le masquage est activé par défaut. Configurez ce comportement via streamOptions. Définissez redact: false uniquement pour des services internes ou des scénarios de débogage dans lesquels vous devez accéder à l’ensemble des données de la requête dans les réponses diffusées en streaming.

const server = new MastraServer({
  app,
  mastra,
  streamOptions: {
    redact: true, // Default
  },
})

Consultez la référence de MastraServer pour connaître toutes les options de configuration.

Remplacement de l’authentification par route

Lorsque l’authentification est configurée sur votre instance Mastra, toutes les routes la requièrent par défaut. Vous pouvez toutefois avoir besoin d’exceptions, par exemple des endpoints publics de vérification de l’état ou des récepteurs de webhooks, ou au contraire des routes d’administration nécessitant des contrôles plus stricts.

Utilisez customRouteAuthConfig pour remplacer le comportement d’authentification de certaines routes. Les clés suivent le format METHOD:PATH, où la méthode est GET, POST, PUT, DELETE ou ALL. Les chemins acceptent les caractères génériques (*) afin de faire correspondre plusieurs routes. Une valeur définie sur false rend la route publique, tandis que true impose une authentification.

const server = new MastraServer({
  app,
  mastra,
  customRouteAuthConfig: new Map([
    // Public health check
    ['GET:/api/health', false],
    // Public API spec
    ['GET:/api/openapi.json', false],
    // Public webhook endpoints
    ['POST:/api/webhooks/*', false],
    // Require auth even if globally disabled
    ['POST:/api/admin/reset', true],
    // Protect all methods on internal routes
    ['ALL:/api/internal/*', true],
  ]),
})

Consultez la référence de MastraServer pour connaître toutes les options de configuration.

Accès à l’application

Après avoir créé l’adaptateur, vous pouvez encore avoir besoin d’accéder à l’application du framework sous-jacent. Cet accès est utile pour la transmettre à la fonction serve d’une plateforme ou pour ajouter des routes depuis un autre module.

// Via the MastraServer instance
const app = server.getApp()

// Via the Mastra instance (available after adapter construction)
const app = mastra.getServerApp()

Les deux méthodes renvoient la même instance d’application. Utilisez celle qui convient le mieux selon les éléments accessibles dans la portée actuelle.

Configuration du serveur et options de l’adaptateur

Avec les adaptateurs de serveur, la configuration provient de deux sources : la configuration server de Mastra (transmise au constructeur Mastra) et les options du constructeur de l’adaptateur. Savoir d’où provient chaque option permet d’éviter toute confusion lorsque certains paramètres semblent ne pas prendre effet.

Paramètres utilisés par les adaptateurs

L’adaptateur lit les paramètres suivants depuis mastra.getServer() :

Option	Description
auth	Configuration de l’authentification, utilisée par registerAuthMiddleware().
bodySizeLimit	Limite par défaut de la taille du corps, en octets. Peut être remplacée pour chaque adaptateur via bodyLimitOptions.
onError	Gestionnaire d’erreurs personnalisé appelé lorsqu’une erreur non gérée survient dans un gestionnaire de route. Consultez server.onError.

Options propres au constructeur de l’adaptateur

Ces options sont transmises directement au constructeur de l’adaptateur et ne sont pas lues depuis la configuration de Mastra :

Option	Description
prefix	Préfixe du chemin des routes
openapiPath	Endpoint de la spécification OpenAPI
bodyLimitOptions	Limite de la taille du corps avec gestionnaire d’erreurs personnalisé
streamOptions	Paramètres de masquage du stream
customRouteAuthConfig	Remplacements de l’authentification par route
mcpOptions	Options de transport MCP (par exemple, serverless: true pour les environnements sans état)

Paramètres non utilisés par les adaptateurs

Les options de configuration server suivantes sont uniquement utilisées par mastra build et n’ont aucun effet lorsque vous utilisez directement des adaptateurs :

Option	Utilisée par
port, host	mastra dev, mastra build
cors	mastra build ajoute un middleware CORS
timeout	mastra build
apiRoutes	registerApiRoute() pour mastra build
middleware	Configuration des middlewares pour mastra build

Lorsque vous utilisez des adaptateurs, configurez ces fonctionnalités directement avec votre framework. Par exemple, ajoutez un middleware CORS à l’aide des packages CORS intégrés de Hono ou d’Express, puis définissez le port lors de l’appel à la fonction d’écoute de votre framework.

Prise en charge de MCP

Les adaptateurs de serveur enregistrent les routes MCP (Model Context Protocol) pendant registerRoutes() lorsque des serveurs MCP sont configurés dans votre instance Mastra. MCP permet à des tools et services externes de se connecter à votre serveur Mastra et d’interagir avec vos agents.

L’adaptateur enregistre des routes pour les transports HTTP et SSE (Server-Sent Events), ce qui permet différents modes de connexion des clients.

Mode serverless

Pour les environnements serverless tels que Cloudflare Workers ou Vercel Edge, activez le mode sans état via mcpOptions.

Lorsque vous utilisez le déployeur Mastra (le parcours standard mastra dev / mastra build), définissez mcpOptions dans la configuration de votre serveur :

const mastra = new Mastra({
  server: {
    mcpOptions: {
      serverless: true,
    },
  },
})

Lorsque vous créez manuellement un adaptateur de serveur, transmettez directement mcpOptions :

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
})

Lorsque serverless: true, les requêtes HTTP MCP s’exécutent sans gestion de session, ce qui les rend compatibles avec les environnements d’exécution sans état.

Consultez la page MCP pour obtenir les détails de configuration et savoir comment mettre en place des serveurs MCP.

Pages connexes

• Adaptateur Hono - Configuration propre à Hono
• Adaptateur Express - Configuration propre à Express
• Adaptateur NestJS - Configuration propre à NestJS
• Adaptateurs personnalisés - Création d’adaptateurs pour d’autres frameworks
• Configuration du serveur - Utilisation de mastra build à la place
• Authentification - Configuration de l’authentification de votre serveur
• Référence de MastraServer - Référence complète de l’API
• Référence de createRoute() - Création de routes personnalisées avec typage sûr