> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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](https://mastra.zisheng.pro/fr/docs/server/mastra-server).
>
> Si vous souhaitez utiliser [Studio](https://mastra.zisheng.pro/fr/docs/studio/overview) avec votre adaptateur de serveur, utilisez [`mastra studio`](https://mastra.zisheng.pro/fr/reference/cli/mastra) pour lancer uniquement l’interface utilisateur de Studio.

## Adaptateurs disponibles

Mastra fournit actuellement les adaptateurs de serveur officiels suivants :

- [@mastra/express](https://mastra.zisheng.pro/fr/reference/server/express-adapter)
- [@mastra/hono](https://mastra.zisheng.pro/fr/reference/server/hono-adapter)
- [@mastra/fastify](https://mastra.zisheng.pro/fr/reference/server/fastify-adapter)
- [@mastra/koa](https://mastra.zisheng.pro/fr/reference/server/koa-adapter)
- [@mastra/nestjs](https://mastra.zisheng.pro/fr/reference/server/nestjs-adapter)

Vous pouvez créer votre propre adaptateur. Pour en savoir plus, consultez la page [Adaptateurs personnalisés](https://mastra.zisheng.pro/fr/docs/server/custom-adapters).

## Installation

Installez l’adaptateur correspondant au framework de votre choix.

**Express**:

**npm**:

```bash
npm install @mastra/express@latest
```

**pnpm**:

```bash
pnpm add @mastra/express@latest
```

**Yarn**:

```bash
yarn add @mastra/express@latest
```

**Bun**:

```bash
bun add @mastra/express@latest
```

**Hono**:

```bash
npm install @mastra/express@latest
```

**Fastify**:

```bash
pnpm add @mastra/express@latest
```

**Koa**:

```bash
yarn add @mastra/express@latest
```

**NestJS**:

```bash
bun add @mastra/express@latest
```

**Tab 6**:

**npm**:

```bash
npm install @mastra/hono@latest
```

**pnpm**:

```bash
pnpm add @mastra/hono@latest
```

**Yarn**:

```bash
yarn add @mastra/hono@latest
```

**Bun**:

```bash
bun add @mastra/hono@latest
```

**Tab 7**:

```bash
npm install @mastra/hono@latest
```

**Tab 8**:

```bash
pnpm add @mastra/hono@latest
```

**Tab 9**:

```bash
yarn add @mastra/hono@latest
```

**Tab 10**:

```bash
bun add @mastra/hono@latest
```

**Tab 11**:

**npm**:

```bash
npm install @mastra/fastify@latest
```

**pnpm**:

```bash
pnpm add @mastra/fastify@latest
```

**Yarn**:

```bash
yarn add @mastra/fastify@latest
```

**Bun**:

```bash
bun add @mastra/fastify@latest
```

**Tab 12**:

```bash
npm install @mastra/fastify@latest
```

**Tab 13**:

```bash
pnpm add @mastra/fastify@latest
```

**Tab 14**:

```bash
yarn add @mastra/fastify@latest
```

**Tab 15**:

```bash
bun add @mastra/fastify@latest
```

**Tab 16**:

**npm**:

```bash
npm install @mastra/koa@latest
```

**pnpm**:

```bash
pnpm add @mastra/koa@latest
```

**Yarn**:

```bash
yarn add @mastra/koa@latest
```

**Bun**:

```bash
bun add @mastra/koa@latest
```

**Tab 17**:

```bash
npm install @mastra/koa@latest
```

**Tab 18**:

```bash
pnpm add @mastra/koa@latest
```

**Tab 19**:

```bash
yarn add @mastra/koa@latest
```

**Tab 20**:

```bash
bun add @mastra/koa@latest
```

**Tab 21**:

**npm**:

```bash
npm install @mastra/nestjs@latest
```

**pnpm**:

```bash
pnpm add @mastra/nestjs@latest
```

**Yarn**:

```bash
yarn add @mastra/nestjs@latest
```

**Bun**:

```bash
bun add @mastra/nestjs@latest
```

**Tab 22**:

```bash
npm install @mastra/nestjs@latest
```

**Tab 23**:

```bash
pnpm add @mastra/nestjs@latest
```

**Tab 24**:

```bash
yarn add @mastra/nestjs@latest
```

**Tab 25**:

```bash
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**:

```typescript
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](https://mastra.zisheng.pro/fr/reference/server/express-adapter) pour connaître toutes les options de configuration.

**Hono**:

```typescript
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](https://mastra.zisheng.pro/fr/reference/server/hono-adapter) pour connaître toutes les options de configuration.

**Fastify**:

```typescript
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](https://mastra.zisheng.pro/fr/reference/server/fastify-adapter) pour connaître toutes les options de configuration.

**Koa**:

```typescript
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](https://mastra.zisheng.pro/fr/reference/server/koa-adapter) pour connaître toutes les options de configuration.

**NestJS**:

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

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

```typescript
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](https://mastra.zisheng.pro/fr/reference/server/nestjs-adapter) 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.

```typescript
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](https://mastra.zisheng.pro/fr/reference/server/express-adapter) et [Hono](https://mastra.zisheng.pro/fr/reference/server/hono-adapter).

## 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`.

```typescript
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` :

```typescript
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.

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

Consultez la référence de [MastraServer](https://mastra.zisheng.pro/fr/reference/server/mastra-server) 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.

```typescript
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](https://mastra.zisheng.pro/fr/reference/server/mastra-server) 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.

```typescript
// 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](https://mastra.zisheng.pro/fr/reference/configuration). |

### 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 :

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

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

```typescript
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](https://mastra.zisheng.pro/fr/docs/mcp/overview) pour obtenir les détails de configuration et savoir comment mettre en place des serveurs MCP.

## Pages connexes

- [Adaptateur Hono](https://mastra.zisheng.pro/fr/reference/server/hono-adapter) - Configuration propre à Hono
- [Adaptateur Express](https://mastra.zisheng.pro/fr/reference/server/express-adapter) - Configuration propre à Express
- [Adaptateur NestJS](https://mastra.zisheng.pro/fr/reference/server/nestjs-adapter) - Configuration propre à NestJS
- [Adaptateurs personnalisés](https://mastra.zisheng.pro/fr/docs/server/custom-adapters) - Création d’adaptateurs pour d’autres frameworks
- [Configuration du serveur](https://mastra.zisheng.pro/fr/docs/server/mastra-server) - Utilisation de `mastra build` à la place
- [Authentification](https://mastra.zisheng.pro/fr/docs/server/auth) - Configuration de l’authentification de votre serveur
- [Référence de MastraServer](https://mastra.zisheng.pro/fr/reference/server/mastra-server) - Référence complète de l’API
- [Référence de createRoute()](https://mastra.zisheng.pro/fr/reference/server/create-route) - Création de routes personnalisées avec typage sûr