Configuration

Cette référence présente toutes les options prises en charge par Mastra. Pour initialiser et configurer Mastra, instanciez la classe Mastra.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  // Your options...
})

Options de premier niveau

agents

Type : Record<string, Agent>

Un registre d’instances d’Agent indexées par leur nom. Les Agents sont des systèmes autonomes capables de prendre des décisions et d’agir à l’aide de modèles d’IA, d’outils et de la mémoire.

Pour en savoir plus, consultez la documentation sur les Agents.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Agent } from '@mastra/core/agent'

export const mastra = new Mastra({
  agents: {
    weatherAgent: new Agent({
      id: 'weather-agent',
      name: 'Weather Agent',
      instructions: 'You help with weather information',
      model: 'openai/gpt-5.6-sol',
    }),
  },
})

backgroundTasks

Type : BackgroundTaskManagerConfig

Active et configure le gestionnaire de tâches en arrière-plan. Lorsqu’il est activé, les Agents peuvent déléguer les appels d’outils de longue durée (y compris les appels de sous-agents) afin qu’ils s’exécutent de manière asynchrone pendant que la boucle agentique se poursuit. Les tâches étant persistées, un backend storage configuré est requis.

Pour en savoir plus, consultez la documentation sur les tâches en arrière-plan.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  backgroundTasks: {
    enabled: true,
    globalConcurrency: 10,
    perAgentConcurrency: 5,
    backpressure: 'queue',
    defaultTimeoutMs: 300_000,
  },
})

enabled:

boolean

= false

Indique si le gestionnaire de tâches en arrière-plan est disponible. Le gestionnaire ne s’initialise que lorsque cette valeur est true et qu’un backend de stockage est configuré. Ce commutateur contrôle uniquement la disponibilité de la fonctionnalité : il n’active l’exécution en arrière-plan pour aucun outil. Les outils doivent l’activer au niveau de l’outil ou de l’Agent (voir le guide sur les tâches en arrière-plan).

globalConcurrency?:

number

= 10

Nombre maximal de tâches en arrière-plan exécutées simultanément pour tous les Agents.

perAgentConcurrency?:

number

= 5

Nombre maximal de tâches en arrière-plan exécutées simultanément pour un seul Agent.

backpressure?:

'queue' | 'reject' | 'fallback-sync'

= 'queue'

Comportement lorsqu’une limite de concurrence est atteinte. 'queue' attend qu’une place se libère, 'reject' lève une erreur lors de la mise en file d’attente et 'fallback-sync' exécute plutôt l’outil de manière synchrone dans la boucle agentique.

defaultTimeoutMs?:

number

= 300000

Délai d’expiration par défaut de chaque tâche, en millisecondes. Peut être remplacé pour chaque outil ou chaque appel.

defaultRetries?:

RetryConfig

Politique de nouvelle tentative appliquée par défaut aux tâches qui échouent.

maxRetries?:

number

Nombre maximal de nouvelles tentatives avant que la tâche soit marquée comme ayant échoué.

retryDelayMs?:

number

Délai entre les nouvelles tentatives, en millisecondes.

backoffMultiplier?:

number

Multiplicateur appliqué à retryDelayMs à chaque tentative suivante.

maxRetryDelayMs?:

number

Limite supérieure du délai de nouvelle tentative, indépendamment du backoff.

retryableErrors?:

(error: Error) => boolean

Prédicat déterminant si une erreur donnée doit entraîner une nouvelle tentative. Par défaut : réessayer pour toutes les erreurs.

cleanup?:

CleanupConfig

Détermine la durée de conservation des enregistrements de tâches et la fréquence d’exécution du processus de nettoyage.

completedTtlMs?:

number

Durée de conservation des enregistrements des tâches terminées, en millisecondes. Par défaut : 1 heure.

failedTtlMs?:

number

Durée de conservation des enregistrements des tâches ayant échoué, en millisecondes. Par défaut : 24 heures.

cleanupIntervalMs?:

number

Fréquence d’exécution du processus de nettoyage, en millisecondes. Par défaut : 1 minute.

waitTimeoutMs?:

number

Durée pendant laquelle la boucle agentique attend qu’une tâche en arrière-plan se termine avant de poursuivre. Si une tâche n’est pas terminée dans ce délai, la boucle continue sans définir isContinued. Par défaut : undefined (ne pas attendre). Peut être remplacé pour chaque Agent ou chaque outil.

onTaskComplete?:

(task: BackgroundTask) => void | Promise<void>

Callback global appelé lorsqu’une tâche en arrière-plan se termine correctement. Il est déclenché en plus des callbacks propres à chaque outil et à chaque Agent.

onTaskFailed?:

(task: BackgroundTask) => void | Promise<void>

Callback global appelé lorsqu’une tâche en arrière-plan échoue. Il est déclenché en plus des callbacks propres à chaque outil et à chaque Agent.

deployer

Type : MastraDeployer

Provider de déploiement permettant de publier des applications sur des plateformes cloud.

Pour en savoir plus, consultez la documentation sur le déploiement.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { NetlifyDeployer } from '@mastra/deployer-netlify'

export const mastra = new Mastra({
  deployer: new NetlifyDeployer(),
})

events

Type : Record<string, EventHandler | EventHandler[]>

Gestionnaires d’événements du système pub/sub interne. Associe les sujets d’événements aux fonctions de gestion appelées lorsque des événements sont publiés sur ces sujets.

attention

Cette option est utilisée en interne par le moteur de Workflow de Mastra. La plupart des utilisateurs n’auront pas besoin de la configurer.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  events: {
    'my-topic': async event => {
      console.log('Event received:', event)
    },
  },
})

gateways

Type : Record<string, MastraModelGateway>

Gateways de routage de modèles personnalisées permettant d’accéder aux providers de LLM. Les gateways gèrent l’authentification propre au provider, la construction des URL et la résolution des modèles. Utilisez cette option pour prendre en charge des providers de LLM personnalisés ou auto-hébergés.

Pour en savoir plus, consultez la documentation sur les gateways personnalisées.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MyPrivateGateway } from './gateways'

export const mastra = new Mastra({
  gateways: {
    private: new MyPrivateGateway(),
  },
})

idGenerator

Type : (context?: IdGeneratorContext) => string
Valeur par défaut : crypto.randomUUID()

Fonction personnalisée de génération d’ID servant à créer des identifiants uniques. Mastra transmet un contexte facultatif afin que vous puissiez générer les ID en fonction de l’élément créé.

IdGeneratorContext comprend :

• idType : 'thread' | 'message' | 'run' | 'step' | 'generic'
• source? : 'agent' | 'workflow' | 'memory'
• entityId? : ID de l’entité Agent/Workflow/mémoire à l’origine de la requête
• threadId? : ID du thread lorsqu’il est pertinent (par exemple, lors de la création d’ID de messages)
• resourceId? : ID de la ressource lorsqu’il est pertinent (par exemple, pour les threads limités à un utilisateur)
• role? : rôle du message lors de la création d’un ID de message
• stepType? : type d’étape du Workflow lors de la création d’un ID d’étape

attention

Cette option est utilisée en interne par Mastra pour créer les ID des exécutions de Workflow, des conversations d’Agent et d’autres ressources. La plupart des utilisateurs n’auront pas besoin de la configurer.

src/mastra/index.ts

import { v4 as uuid } from '@lukeed/uuid'
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  idGenerator: context => {
    if (context?.idType === 'message' && context?.threadId) {
      return `msg-${context.threadId}-${uuid()}`
    }

    if (context?.idType === 'run' && context?.source && context?.entityId) {
      return `${context.source}-run-${context.entityId}-${uuid()}`
    }

    return uuid()
  },
})

logger

Type : IMastraLogger | false
Valeur par défaut : ConsoleLogger avec le niveau INFO en développement et WARN en production

Implémentation du logger pour la journalisation et le débogage de l’application. Définissez-la sur false pour désactiver complètement la journalisation.

Pour en savoir plus, consultez la documentation sur la journalisation.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'

export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'MyApp', level: 'debug' }),
})

mcpServers

Type : Record<string, MCPServerBase>

Serveurs MCP (Model Context Protocol) qui exposent les outils, Agents, Workflows et ressources de Mastra aux clients compatibles avec MCP. Utilisez cette option pour créer vos propres serveurs MCP, accessibles depuis tout système prenant en charge le protocole.

Pour en savoir plus, consultez la présentation de MCP.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MCPServer } from '@mastra/mcp'

const mcpServer = new MCPServer({
  id: 'my-mcp-server',
  name: 'My MCP Server',
  version: '1.0.0',
})

export const mastra = new Mastra({
  mcpServers: {
    myServer: mcpServer,
  },
})

memory

Type : Record<string, MastraMemory>

Un registre d’instances de mémoire auxquelles les Agents peuvent faire référence. La mémoire assure la cohérence des Agents entre les interactions en conservant les informations pertinentes des conversations précédentes. Mastra prend en charge l’historique des messages récents et la mémoire de travail pour les informations persistantes propres à l’utilisateur. Le rappel sémantique récupère les messages plus anciens en fonction de leur pertinence.

Pour en savoir plus, consultez la documentation sur la mémoire.

remarque

La plupart des utilisateurs configurent la mémoire directement sur les Agents. Cette configuration de premier niveau sert à définir des instances de mémoire réutilisables et partageables entre plusieurs Agents.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: ':memory:',
  }),
  memory: {
    chatMemory: new Memory({
      options: {
        lastMessages: 20,
      },
    }),
  },
})

observability

Type : ObservabilityEntrypoint

Mastra fournit des fonctionnalités d’observabilité pour les applications d’IA. Surveillez les opérations des LLM, tracez les décisions des Agents et déboguez les Workflows complexes avec des outils qui comprennent les schémas propres à l’IA. Le tracing capture les interactions avec les modèles, les chemins d’exécution des Agents, les appels d’outils et les étapes des Workflows.

Pour en savoir plus, consultez la documentation sur l’observabilité.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'
import { Observability, MastraStorageExporter } from '@mastra/observability'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})

processors

Type : Record<string, Processor>

Processeurs d’entrée/sortie permettant de transformer les entrées et les sorties des Agents. Les processeurs s’exécutent à des points précis du pipeline d’exécution de l’Agent, ce qui permet de modifier les entrées avant qu’elles n’atteignent le modèle de langage ou les sorties avant leur renvoi. Utilisez-les pour ajouter des garde-fous, détecter les injections de prompt, modérer le contenu ou appliquer une logique métier personnalisée.

Pour en savoir plus, consultez la documentation sur les processeurs.

remarque

La plupart des utilisateurs configurent les processeurs directement sur les Agents. Cette configuration de premier niveau sert à définir des instances de processeur réutilisables et partageables entre plusieurs Agents.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { ModerationProcessor } from '@mastra/core/processors'

export const mastra = new Mastra({
  processors: {
    moderation: new ModerationProcessor({
      model: 'openai/gpt-5-mini',
      categories: ['hate', 'harassment', 'violence'],
    }),
  },
})

pubsub

Type : PubSub
Valeur par défaut : EventEmitterPubSub

Système pub/sub pour la communication événementielle entre les composants. Mastra l’utilise en interne pour traiter les événements des Workflows et assurer la communication entre les composants.

attention

Cette option est utilisée en interne par Mastra. La plupart des utilisateurs n’auront pas besoin de la configurer.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { CustomPubSub } from './pubsub'

export const mastra = new Mastra({
  pubsub: new CustomPubSub(),
})

scorers

Type : Record<string, Scorer>

Les Scorers évaluent la qualité des réponses des Agents et des sorties des Workflows. Ils fournissent des métriques quantifiables pour mesurer la qualité des Agents au moyen de méthodes fondées sur l’évaluation par un modèle, sur des règles ou sur des statistiques. Utilisez les Scorers pour suivre les performances et comparer les approches. Ils permettent également d’identifier les points à améliorer.

Pour en savoir plus, consultez la documentation sur les Scorers.

remarque

La plupart des utilisateurs configurent les Scorers directement sur les Agents. Cette configuration de premier niveau sert à définir des instances de Scorer réutilisables et partageables entre plusieurs Agents.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { createToxicityScorer } from '@mastra/evals/scorers/prebuilt'

export const mastra = new Mastra({
  scorers: {
    toxicity: createToxicityScorer({ model: 'openai/gpt-5-mini' }),
  },
})

storage

Type : MastraCompositeStore

Provider de stockage permettant de persister les données de l’application. Il est utilisé par la mémoire, les Workflows, les traces et les autres composants nécessitant une persistance. Mastra prend en charge plusieurs backends de base de données, notamment PostgreSQL, MongoDB et libSQL.

Pour en savoir plus, consultez la documentation sur le stockage.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})

tools

Type : Record<string, Tool>

Les Tools sont des fonctions réutilisables que les Agents peuvent employer pour interagir avec des systèmes externes. Chaque Tool définit ses entrées, ses sorties et sa logique d’exécution.

Pour en savoir plus, consultez la documentation sur les Tools.

remarque

La plupart des utilisateurs configurent les Tools directement sur les Agents. Cette configuration de premier niveau sert à définir des Tools réutilisables et partageables entre plusieurs Agents.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

const weatherTool = createTool({
  id: 'get-weather',
  description: 'Fetches weather for a city',
  inputSchema: z.object({
    city: z.string(),
  }),
  execute: async () => {
    return { temperature: 20, conditions: 'Sunny' }
  },
})

export const mastra = new Mastra({
  tools: {
    weather: weatherTool,
  },
})

tts

Type : Record<string, MastraVoice>

Providers de synthèse vocale. Enregistrez des providers vocaux afin que les Agents puissent convertir leurs réponses textuelles en audio parlé.

Pour en savoir plus, consultez la documentation sur la voix.

remarque

La plupart des utilisateurs configurent la voix directement sur les Agents. Cette configuration de premier niveau sert à définir des providers vocaux réutilisables et partageables entre plusieurs Agents.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { OpenAIVoice } from '@mastra/voice-openai'

export const mastra = new Mastra({
  tts: {
    openai: new OpenAIVoice(),
  },
})

vectors

Type : Record<string, MastraVector>

Stores vectoriels pour la recherche sémantique et les embeddings. Ils sont utilisés dans les pipelines RAG, la recherche par similarité et d’autres fonctionnalités fondées sur les embeddings. Mastra prend en charge plusieurs bases de données vectorielles, notamment Pinecone, PostgreSQL avec pgvector, OracleDB et MongoDB.

Pour en savoir plus, consultez la documentation sur le RAG.

remarque

La plupart des utilisateurs créent directement les stores vectoriels lors de la construction de pipelines RAG. Cette configuration de premier niveau sert à définir des instances de store vectoriel réutilisables et partageables dans toute votre application.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { PineconeVector } from '@mastra/pinecone'

export const mastra = new Mastra({
  vectors: {
    pinecone: new PineconeVector({
      id: 'pinecone-vector',
      apiKey: process.env.PINECONE_API_KEY,
    }),
  },
})

workflows

Type : Record<string, Workflow>

Les Workflows définissent des pipelines d’exécution par étapes, avec des entrées et des sorties dont les types sont sûrs. Utilisez-les pour les tâches comportant plusieurs étapes dans un ordre d’exécution précis, afin de contrôler la circulation des données entre les étapes.

Pour en savoir plus, consultez la documentation sur les Workflows.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { testWorkflow } from './workflows/test-workflow'

export const mastra = new Mastra({
  workflows: {
    testWorkflow,
  },
})

workspace

Type : Workspace

Un Workspace Mastra fournit aux Agents un environnement persistant pour stocker des fichiers et exécuter des commandes. Les Agents héritent du Workspace global de la classe Mastra, sauf si leur propre Workspace est configuré.

Consultez la documentation sur le Workspace pour connaître les détails d’implémentation.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
})

const mastra = new Mastra({
  workspace,
})

Options du bundler

bundler.entries

Type : Record<string, string>
Valeur par défaut : {}

Points d’entrée de processus supplémentaires à générer avec le bundle du serveur, sous la forme d’une correspondance entre le nom de sortie et le chemin source relatif à votre répertoire Mastra. Chaque entrée produit son propre fichier <name>.mjs dans .mastra/output.

Utilisez cette option pour les processus de longue durée qui s’exécutent à côté de votre serveur Mastra plutôt qu’en son sein, comme un worker vocal LiveKit. Le point d’entrée partage avec le serveur le répertoire de sortie, le fichier package.json et les dépendances installées. Une seule commande mastra build produit ainsi un artefact déployable que vous pouvez démarrer avec différentes commandes.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    entries: { 'voice-worker': './voice-worker.ts' },
  },
})

Cela génère .mastra/output/voice-worker.mjs à côté de .mastra/output/index.mjs. Les dépendances importées uniquement par le point d’entrée supplémentaire sont également analysées, afin d’être installées dans la sortie.

Les noms d’entrée peuvent contenir / afin d’imbriquer la sortie. Ils ne peuvent pas être index, réservé au bundle du serveur, ni tools, réservé à l’agrégateur de Tools, et ne peuvent pas commencer par tools/, réservé aux bundles de Tools.

remarque

mastra build applique la valeur par défaut de bundler.externals, à savoir true, uniquement lorsqu’aucune option du bundler n’est définie. Dès que vous définissez entries, définissez également externals explicitement si votre point d’entrée supplémentaire dépend de packages qui ne peuvent pas être intégrés au bundle, comme des modules natifs.

bundler.externals

Type : boolean | string[]
Valeur par défaut : true

Lorsque vous exécutez mastra build, Mastra regroupe votre projet dans le répertoire .mastra/output. Cette option détermine les packages exclus du bundle (marqués comme « externes ») et installés séparément par un gestionnaire de packages. Elle est utile lorsque le bundler interne de Mastra (Rollup) rencontre des difficultés pour regrouper certains packages.

Par défaut, mastra build définit cette option sur true.

Les valeurs ont les significations suivantes :

• true : toutes les dépendances répertoriées dans le fichier package.json de votre projet sont marquées comme externes
• false : aucune dépendance n’est marquée comme externe ; tout est regroupé dans le bundle
• string[] : tableau des noms de packages à marquer comme externes ; les autres sont regroupés dans le bundle

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    externals: ['some-package', 'another-package'],
  },
})

bundler.sourcemap

Type : boolean
Valeur par défaut : false

Active la génération de source maps pour la sortie regroupée.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    sourcemap: true,
  },
})

bundler.transpilePackages

Type : string[]
Valeur par défaut : []

Liste des packages dont le code source doit être transpilé par esbuild pendant le processus de build. Utilisez cette option pour les dépendances qui contiennent du TypeScript ou un autre code devant être compilé avant la mise en bundle.

Cette option n’est nécessaire que si vous importez directement du code source non compilé. Si vos packages sont déjà compilés en CommonJS ou en ESM, il est inutile de les répertorier ici.

Mastra détecte automatiquement les packages du Workspace dans les monorepos et les ajoute à cette liste. En général, vous devez donc uniquement préciser les packages externes qui nécessitent une transpilation.

Pendant le build, Mastra résout également les alias de tsconfig.json baseUrl et paths. Cela inclut les imports de style ESM, tels que ~/utils/logger.js, qui pointent vers des fichiers sources TypeScript.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    transpilePackages: ['@my-org/shared-utils'],
  },
})

Options du serveur

server.apiRoutes

Type : ApiRoute[]

Mastra expose automatiquement les Agents et les Workflows enregistrés par l’intermédiaire de son serveur. Pour ajouter d’autres comportements, vous pouvez définir vos propres routes HTTP.

Pour en savoir plus, consultez la documentation sur les routes d’API personnalisées.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { registerApiRoute } from '@mastra/core/server'

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      registerApiRoute('/my-custom-route', {
        method: 'GET',
        handler: async c => {
          return c.json({ message: 'Custom route' })
        },
      }),
    ],
  },
})

server.auth

Type : MastraAuthConfig | MastraAuthProvider

Configuration de l’authentification du serveur. Mastra prend en charge plusieurs providers d’authentification, notamment JWT, Clerk, Supabase, Firebase, WorkOS et Auth0.

Pour en savoir plus, consultez la documentation sur l’authentification.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraJwtAuth } from '@mastra/auth'

export const mastra = new Mastra({
  server: {
    auth: new MastraJwtAuth({
      secret: process.env.MASTRA_JWT_SECRET,
      mapUserToResourceId: user => user.id,
    }),
  },
})

Le callback mapUserToResourceId associe l’utilisateur authentifié à un ID de ressource afin de limiter la portée de la mémoire et des threads. Lorsqu’il est fourni, il est appelé après une authentification réussie et la valeur renvoyée est définie dans le contexte de la requête sous la clé MASTRA_RESOURCE_ID_KEY. Pour plus de détails, consultez Autorisation (isolation des utilisateurs).

server.bodySizeLimit

Type : number
Valeur par défaut : 4_718_592 (4,5 Mo)

Taille maximale du corps de la requête, en octets. Augmentez cette limite si votre application doit traiter des charges utiles plus volumineuses.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    bodySizeLimit: 10 * 1024 * 1024, // 10mb
  },
})

server.mcpOptions

Type : object
Valeur par défaut : undefined

Options de transport MCP appliquées à toutes les routes MCP HTTP et SSE. Utilisez-les pour activer le mode sans état dans les environnements serverless (Cloudflare Workers, Vercel Edge, AWS Lambda, etc.), où les connexions persistantes et l’état de session en mémoire ne sont pas disponibles.

Propriété	Type	Valeur par défaut	Description
serverless	boolean	false	Exécute MCP en mode sans état, sans gestion des sessions
sessionIdGenerator	() => string	undefined	Fonction personnalisée de génération d’ID de session

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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

server.build

Configuration des fonctionnalités du serveur au moment du build. Ces options contrôlent les outils de développement tels que Swagger UI et la journalisation des requêtes, activés pendant le développement local mais désactivés par défaut en production.

Propriété	Type	Valeur par défaut	Description
swaggerUI	boolean	false	Active Swagger UI à l’adresse /swagger-ui pour explorer l’API de manière interactive (nécessite que openAPIDocs soit défini sur true)
apiReqLogs	boolean	false	Active la journalisation des requêtes d’API dans la console
openAPIDocs	boolean	false	Active la spécification OpenAPI à l’adresse /api/openapi.json. Les routes Mastra intégrées utilisent servers: [{url: "/api"}], tandis que les routes personnalisées reçoivent une valeur de remplacement servers: [{url: "/"}] propre à chaque chemin.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    build: {
      swaggerUI: true,
      apiReqLogs: true,
      openAPIDocs: true,
    },
  },
})

server.cors

Type : CorsOptions | false

Configuration CORS (Cross-Origin Resource Sharing) du serveur. Définissez-la sur false pour désactiver complètement CORS. Utilisez cette option afin d’appliquer une politique unique à toutes les routes. Pour une politique personnalisée propre à une route, utilisez l’option cors de registerApiRoute().

Propriété	Type	Valeur par défaut	Description
origin	string | string[]	'*'	Origines des requêtes CORS
allowMethods	string[]	['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']	Méthodes HTTP
allowHeaders	string[]	['Content-Type', 'Authorization', 'x-mastra-client-type', 'x-mastra-dev-playground']	En-têtes de requête
exposeHeaders	string[]	['Content-Length', 'X-Requested-With']	En-têtes exposés au navigateur
credentials	boolean	false	Identifiants (cookies, en-têtes d’autorisation)
maxAge	number	3600	Durée de mise en cache de la requête préliminaire, en secondes

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    cors: {
      origin: ['https://example.com'],
      allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
      allowHeaders: ['Content-Type', 'Authorization'],
      credentials: false,
    },
  },
})

server.host

Type : string
Valeur par défaut : localhost (ou la variable d’environnement MASTRA_HOST si elle est définie)

Adresse d’hôte à laquelle le serveur de développement Mastra se lie. Si la variable d’environnement MASTRA_HOST est définie, elle prévaut sur la valeur par défaut.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    host: '0.0.0.0',
  },
})

server.https

Type : { key: Buffer; cert: Buffer }

Configuration HTTPS permettant d’exécuter le serveur de développement avec TLS. Mastra prend en charge le développement HTTPS local au moyen du flag mastra dev --https, qui crée et gère automatiquement les certificats. Pour gérer vous-même les certificats, fournissez vos propres fichiers de clé et de certificat :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import fs from 'node:fs'

export const mastra = new Mastra({
  server: {
    https: {
      key: fs.readFileSync('path/to/key.pem'),
      cert: fs.readFileSync('path/to/cert.pem'),
    },
  },
})

server.middleware

Type : Middleware | Middleware[]

Fonctions middleware personnalisées qui interceptent les requêtes avant ou après les gestionnaires de routes. Un middleware peut servir à l’authentification, à la journalisation, à l’injection d’un contexte propre à la requête ou à l’ajout d’en-têtes. Chaque middleware reçoit le Context Hono et une fonction next. Renvoyez une Response pour interrompre le traitement de la requête, ou appelez next() pour le poursuivre.

Pour en savoir plus, consultez la documentation sur les middlewares.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    middleware: [
      {
        handler: async (c, next) => {
          const authHeader = c.req.header('Authorization')
          if (!authHeader) {
            return new Response('Unauthorized', { status: 401 })
          }
          await next()
        },
        path: '/api/*',
      },
    ],
  },
})

server.onError

Type : (err: Error, c: Context) => Response | Promise<Response>

Gestionnaire d’erreurs personnalisé appelé lorsqu’une erreur non gérée se produit. Utilisez-le pour personnaliser les réponses d’erreur, journaliser les erreurs dans des services externes tels que Sentry ou implémenter un formatage personnalisé des erreurs.

Ce hook est pris en charge par tous les adaptateurs de serveur. Le paramètre c fournit un objet de contexte compatible avec Hono. Pour les adaptateurs autres que Hono (Koa, Express et Fastify), un shim fournit les méthodes courantes telles que c.json() et c.req.path.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import * as Sentry from '@sentry/node'

export const mastra = new Mastra({
  server: {
    onError: (err, c) => {
      Sentry.captureException(err)

      return c.json(
        {
          error: err.message,
          timestamp: new Date().toISOString(),
        },
        500,
      )
    },
  },
})

server.onValidationError

Type : (error: ZodError, context: 'query' | 'body' | 'path') => { status: number; body: unknown } | undefined

Gestionnaire personnalisé appelé lorsqu’une requête échoue à la validation du schéma Zod. Utilisez-le pour personnaliser les réponses aux erreurs de validation, modifier le code de statut ou formater les erreurs conformément aux normes de votre API.

Renvoyez un objet { status, body } pour remplacer la réponse 400 par défaut, ou undefined pour conserver le comportement par défaut. Ce hook est pris en charge par tous les adaptateurs de serveur (Hono, Express, Fastify et Koa).

Le paramètre context indique la partie de la requête qui a échoué à la validation :

• 'query' : paramètres de requête
• 'body' : corps de la requête
• 'path' : paramètres du chemin

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    onValidationError: (error, context) => ({
      status: 422,
      body: {
        ok: false,
        errors: error.issues.map(i => ({
          path: i.path.join('.'),
          message: i.message,
        })),
        source: context,
      },
    }),
  },
})

Vous pouvez également définir onValidationError sur chaque route créée avec createRoute(). Un hook défini au niveau de la route prévaut sur celui défini au niveau du serveur.

server.port

Type : number
Valeur par défaut : 4111 (ou la variable d’environnement PORT si elle est définie)

Port auquel le serveur de développement Mastra se lie. Si la variable d’environnement PORT est définie, elle prévaut sur la valeur par défaut.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    port: 8080,
  },
})

server.studioBase

Type : string
Valeur par défaut : /

Chemin de base pour héberger Studio. Utilisez cette option afin d’héberger Studio dans un sous-chemin de votre application existante plutôt qu’à la racine.

Cette option est utile lors de l’intégration à des applications existantes, de l’utilisation d’outils d’authentification tels que Cloudflare Zero Trust qui tirent parti de domaines partagés, ou de la gestion de plusieurs services sous un même domaine.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    studioBase: '/my-mastra-studio',
  },
})

Exemples d’URL :

• Par défaut : http://localhost:4111/ (Studio à la racine)
• Avec studioBase : http://localhost:4111/my-mastra-studio/ (Studio dans un sous-chemin)

server.timeout

Type : number
Valeur par défaut : 180000 (3 minutes)

Délai d’expiration des requêtes, en millisecondes. Les requêtes qui dépassent cette durée sont interrompues.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    timeout: 30000, // 30 seconds
  },
})