設定

以下のリファレンスでは、Mastra がサポートするすべてのオプションを説明します。Mastra クラスをインスタンス化して、Mastra を初期化および設定します。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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

トップレベルオプション

agents

型： Record<string, Agent>

名前をキーとする Agent インスタンスのレコードです。Agent は、AI モデル、Tool、Memory を使用して意思決定と操作を行える自律システムです。

詳しくは、Agent のドキュメントを参照してください。

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

型： BackgroundTaskManagerConfig

バックグラウンドタスクマネージャーを有効化して設定します。有効にすると、Agent は長時間実行される Tool 呼び出し（Subagent の呼び出しを含む）を非同期実行としてディスパッチでき、その間も Agent ループは継続します。タスクは永続化されるため、storage バックエンドの設定が必要です。

詳しくは、バックグラウンドタスクのドキュメントを参照してください。

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

バックグラウンドタスクマネージャーを利用可能にするかどうか。これは true で、かつ storage バックエンドが設定されている場合にのみ初期化されます。これは機能の利用可否を切り替えるスイッチであり、Tool のバックグラウンドディスパッチを有効にするものではありません。Tool または Agent のレイヤーで明示的に有効化する必要があります（バックグラウンドタスクガイドを参照）。

globalConcurrency?:

number

= 10

すべての Agent を通じて同時実行できるバックグラウンドタスクの最大数。

perAgentConcurrency?:

number

= 5

1つの Agent で同時実行できるバックグラウンドタスクの最大数。

backpressure?:

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

= 'queue'

同時実行数の上限に達した場合の動作。'queue' は空きを待ち、'reject' はキューへの追加時に例外をスローし、'fallback-sync' は代わりに Agent ループ内で Tool を同期実行します。

defaultTimeoutMs?:

number

= 300000

タスクごとのデフォルトタイムアウト（ミリ秒）。Tool ごと、または呼び出しごとに上書きできます。

defaultRetries?:

RetryConfig

失敗したタスクに適用されるデフォルトの再試行ポリシー。

maxRetries?:

number

タスクが失敗と記録されるまでの最大再試行回数。

retryDelayMs?:

number

再試行間の遅延（ミリ秒）。

backoffMultiplier?:

number

2回目以降の各試行で retryDelayMs に適用される乗数。

maxRetryDelayMs?:

number

バックオフにかかわらず適用される再試行遅延の上限。

retryableErrors?:

(error: Error) => boolean

指定したエラーを再試行するか決定する述語。デフォルトでは、すべてのエラーを再試行します。

cleanup?:

CleanupConfig

タスクレコードの保持期間と、クリーンアップ処理の実行頻度を制御します。

completedTtlMs?:

number

完了したタスクレコードの保持期間（ミリ秒）。デフォルトは1時間です。

failedTtlMs?:

number

失敗したタスクレコードの保持期間（ミリ秒）。デフォルトは24時間です。

cleanupIntervalMs?:

number

クリーンアップ処理の実行間隔（ミリ秒）。デフォルトは1分です。

waitTimeoutMs?:

number

Agent ループが次に進むまで、バックグラウンドタスクの完了を待つ時間。タスクがこの時間内に完了しない場合、ループは isContinued を設定せずに続行します。デフォルトは undefined（待機しない）です。Agent ごと、または Tool ごとに上書きできます。

onTaskComplete?:

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

いずれかのバックグラウンドタスクが正常に完了したときに呼び出されるグローバルコールバック。Tool ごと、および Agent ごとのコールバックに加えて実行されます。

onTaskFailed?:

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

いずれかのバックグラウンドタスクが失敗したときに呼び出されるグローバルコールバック。Tool ごと、および Agent ごとのコールバックに加えて実行されます。

deployer

型： MastraDeployer

アプリケーションをクラウドプラットフォームへ公開するためのデプロイ Provider です。

詳しくは、デプロイのドキュメントを参照してください。

src/mastra/index.ts

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

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

events

型： Record<string, EventHandler | EventHandler[]>

内部 pub/sub システム用のイベントハンドラーです。イベントトピックを、そのトピックへイベントが公開されたときに呼び出されるハンドラー関数へ対応付けます。

警告

これは Mastra の Workflow エンジンが内部で使用します。ほとんどのユーザーは、このオプションを設定する必要はありません。

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

型： Record<string, MastraModelGateway>

LLM Provider にアクセスするためのカスタムモデルルーター Gateway です。Gateway は、Provider 固有の認証、URL の構築、モデルの解決を処理します。カスタムまたはセルフホストの LLM Provider をサポートする場合に使用します。

詳しくは、カスタム Gateway のドキュメントを参照してください。

src/mastra/index.ts

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

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

idGenerator

型： (context?: IdGeneratorContext) => string
デフォルト： crypto.randomUUID()

一意な識別子を作成するためのカスタム ID 生成関数です。Mastra は任意のコンテキストを渡すため、作成対象に応じた ID を生成できます。

IdGeneratorContext には次の項目が含まれます。

• idType：'thread' | 'message' | 'run' | 'step' | 'generic'
• source?：'agent' | 'workflow' | 'memory'
• entityId?：要求元の Agent、Workflow、Memory エンティティの ID
• threadId?：関連する場合の Thread ID（Message ID の作成時など）
• resourceId?：関連する場合の Resource ID（ユーザースコープの Thread など）
• role?：Message ID の作成時に使用する Message の Role
• stepType?：Step ID の作成時に使用する Workflow Step の型

警告

これは、Workflow の実行、Agent の会話、その他のリソース用の ID を作成するために Mastra が内部で使用します。ほとんどのユーザーは、このオプションを設定する必要はありません。

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

型： IMastraLogger | false
デフォルト： 開発環境では INFO レベル、本番環境では WARN レベルの ConsoleLogger

アプリケーションのログ記録とデバッグに使用する Logger 実装です。ログ記録を完全に無効化するには、false に設定します。

詳しくは、ログのドキュメントを参照してください。

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

型： Record<string, MCPServerBase>

Mastra の Tool、Agent、Workflow、リソースを MCP 互換クライアントへ公開する MCP（Model Context Protocol）サーバーです。このオプションを使用すると、プロトコルをサポートする任意のシステムから利用できる独自の MCP サーバーを作成できます。

詳しくは、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

型： Record<string, MastraMemory>

Agent から参照できる Memory インスタンスのレジストリです。Memory は過去の会話から関連情報を保持し、やり取りを通じて Agent の一貫性を維持します。Mastra は、最近の Message を保持する Message 履歴と、ユーザー固有の詳細を永続化する Working Memory をサポートしています。Semantic Recall は、関連性に基づいて以前の Message を取得します。

詳しくは、Memory のドキュメントを参照してください。

注記

ほとんどのユーザーは、Agent に Memory を直接設定します。このトップレベル設定は、複数の Agent で共有できる再利用可能な Memory インスタンスを定義するためのものです。

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

型： ObservabilityEntrypoint

Mastra は、AI アプリケーション向けの Observability 機能を提供します。AI 固有のパターンを理解する Tool により、LLM の動作を監視し、Agent の意思決定を Trace し、複雑な Workflow をデバッグできます。Tracing は、モデルとのやり取り、Agent の実行経路、Tool の呼び出し、Workflow の Step を記録します。

詳しくは、Observability のドキュメントを参照してください。

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

型： Record<string, Processor>

Agent の入力と出力を変換する入出力 Processor です。Processor は Agent の実行パイプライン内の特定の時点で動作し、言語モデルへ届く前の入力や、返される前の出力を変更できます。Processor を使用して、Guardrail の追加、Prompt Injection の検出、コンテンツのモデレーション、カスタムビジネスロジックの適用を行えます。

詳しくは、Processor のドキュメントを参照してください。

注記

ほとんどのユーザーは、Agent に Processor を直接設定します。このトップレベル設定は、複数の Agent で共有できる再利用可能な Processor インスタンスを定義するためのものです。

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

型： PubSub
デフォルト： EventEmitterPubSub

コンポーネント間のイベント駆動通信に使用する pub/sub システムです。Workflow のイベント処理とコンポーネント間通信のために、Mastra が内部で使用します。

警告

これは Mastra が内部で使用します。ほとんどのユーザーは、このオプションを設定する必要はありません。

src/mastra/index.ts

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

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

scorers

型： Record<string, Scorer>

Scorer は、Agent の応答と Workflow の出力品質を評価します。モデルによる評価、ルールベース、統計的手法を使用して Agent の品質を測定する、定量化可能な指標を提供します。Scorer を使用してパフォーマンスを追跡し、手法を比較できます。改善が必要な領域の特定にも利用できます。

詳しくは、Scorer のドキュメントを参照してください。

注記

ほとんどのユーザーは、Agent に Scorer を直接設定します。このトップレベル設定は、複数の Agent で共有できる再利用可能な Scorer インスタンスを定義するためのものです。

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

型： MastraCompositeStore

アプリケーションデータを永続化する Storage Provider です。Memory、Workflow、Trace、および永続化が必要なその他のコンポーネントによって使用されます。Mastra は PostgreSQL、MongoDB、libSQL など、複数のデータベースバックエンドをサポートしています。

詳しくは、Storage のドキュメントを参照してください。

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

型： Record<string, Tool>

Tool は、Agent が外部システムとやり取りするために使用できる再利用可能な関数です。各 Tool は、入力、出力、実行ロジックを定義します。

詳しくは、Tool のドキュメントを参照してください。

注記

ほとんどのユーザーは、Agent に Tool を直接設定します。このトップレベル設定は、複数の Agent で共有できる再利用可能な Tool を定義するためのものです。

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

型： Record<string, MastraVoice>

音声合成機能用の Text-to-Speech Provider です。Voice Provider を登録すると、Agent がテキスト応答を音声へ変換できるようになります。

詳しくは、Voice のドキュメントを参照してください。

注記

ほとんどのユーザーは、Agent に Voice を直接設定します。このトップレベル設定は、複数の Agent で共有できる再利用可能な Voice Provider を定義するためのものです。

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

型： Record<string, MastraVector>

Semantic Search と Embedding 用の Vector Store です。RAG パイプライン、類似検索、その他の Embedding ベースの機能で使用されます。Mastra は Pinecone、pgvector を使用した PostgreSQL、OracleDB、MongoDB など、複数の Vector Database をサポートしています。

詳しくは、RAG のドキュメントを参照してください。

注記

ほとんどのユーザーは、RAG パイプラインの構築時に Vector Store を直接作成します。このトップレベル設定は、アプリケーション全体で共有できる再利用可能な Vector Store インスタンスを定義するためのものです。

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

型： Record<string, Workflow>

Workflow は、型安全な入力と出力を持つ Step ベースの実行パイプラインを定義します。特定の実行順序で複数の Step を処理するタスクには Workflow を使用します。Step 間のデータフローを制御できます。

詳しくは、Workflow のドキュメントを参照してください。

src/mastra/index.ts

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

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

workspace

型： Workspace

Mastra Workspace は、ファイルの保存とコマンド実行に使用できる永続的な環境を Agent に提供します。Agent に独自の Workspace が設定されていない場合、Mastra クラスのグローバル Workspace を継承します。

実装の詳細は、Workspace のドキュメントを参照してください。

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,
})

Bundler オプション

bundler.entries

型： Record<string, string>
デフォルト： {}

サーバーバンドルとともに出力する追加のプロセスエントリーです。出力名を、Mastra ディレクトリからの相対ソースパスへ対応付けます。各エントリーは .mastra/output 内に個別の <name>.mjs として生成されます。

LiveKit Voice Worker のように、Mastra サーバーの内部ではなく、その横で動作する長時間実行プロセスに使用します。エントリーはサーバーと出力ディレクトリ、package.json、インストール済みの依存関係を共有するため、1回の mastra build で異なるコマンドから起動できる1つのデプロイ可能な成果物が生成されます。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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

これにより、.mastra/output/index.mjs と同じ場所に .mastra/output/voice-worker.mjs が生成されます。追加エントリーだけが import する依存関係も解析され、出力へインストールされます。

エントリー名には / を含めて、出力をネストできます。サーバーバンドルである index、Tool Aggregator である tools は使用できません。また、Tool バンドル用に予約されているため、tools/ で始めることもできません。

注記

mastra build が bundler.externals のデフォルト値 true を適用するのは、Bundler オプションを一切設定していない場合だけです。entries を設定した場合、追加エントリーがネイティブモジュールなどバンドルできないパッケージに依存するなら、externals も明示的に設定してください。

bundler.externals

型： boolean | string[]
デフォルト： true

mastra build を実行すると、Mastra はプロジェクトを .mastra/output ディレクトリへバンドルします。このオプションでは、バンドルから除外し（「external」としてマークし）、パッケージマネージャーを通じて別途インストールするパッケージを制御します。Mastra の内部 Bundler（Rollup）でパッケージを正常にバンドルできない場合に便利です。

デフォルトでは、mastra build はこのオプションを true に設定します。

各値には次の意味があります。

• true：プロジェクトの package.json に記載されたすべての依存関係を external としてマークします。
• false：依存関係を external としてマークせず、すべてをまとめてバンドルします。
• string[]：external としてマークするパッケージ名の配列です。残りはまとめてバンドルされます。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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

bundler.sourcemap

型： boolean
デフォルト： false

バンドル出力のソースマップ生成を有効にします。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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

bundler.transpilePackages

型： string[]
デフォルト： []

ビルド処理中に esbuild でソースコードをトランスパイルするパッケージの一覧です。TypeScript など、バンドル前にコンパイルが必要なコードを含む依存関係に使用します。

このオプションが必要なのは、未コンパイルのソースコードを直接 import する場合だけです。パッケージがすでに CommonJS または ESM へコンパイルされている場合、ここに記載する必要はありません。

Mastra は monorepo 構成の Workspace パッケージを自動検出してこの一覧へ追加するため、通常はトランスパイルが必要な外部パッケージだけを指定します。

Mastra はビルド時に tsconfig.json の baseUrl と paths エイリアスも解決します。これには、TypeScript ソースファイルを指す ~/utils/logger.js などの ESM 形式の import も含まれます。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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

サーバーオプション

server.apiRoutes

型： ApiRoute[]

Mastra は、登録済みの Agent と Workflow をサーバー経由で自動的に公開します。動作を追加するには、独自の HTTP ルートを定義できます。

詳しくは、カスタム API ルートのドキュメントを参照してください。

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

型： MastraAuthConfig | MastraAuthProvider

サーバーの認証設定です。Mastra は JWT、Clerk、Supabase、Firebase、WorkOS、Auth0 など、複数の認証 Provider をサポートしています。

詳しくは、認証のドキュメントを参照してください。

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,
    }),
  },
})

mapUserToResourceId コールバックは、認証済みユーザーを Memory または Thread のスコープに使用する Resource ID へ対応付けます。指定すると、認証成功後に呼び出され、戻り値がリクエストコンテキストの MASTRA_RESOURCE_ID_KEY に設定されます。詳しくは、認可（ユーザー分離）を参照してください。

server.bodySizeLimit

型： number
デフォルト： 4_718_592（4.5 MB）

リクエストボディの最大サイズ（バイト）です。アプリケーションでより大きなペイロードを処理する必要がある場合は、この上限を増やしてください。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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

server.mcpOptions

型： object
デフォルト： undefined

すべての MCP HTTP ルートと SSE ルートに適用する MCP Transport オプションです。永続的な接続やインメモリーのセッション状態を利用できないサーバーレス環境（Cloudflare Workers、Vercel Edge、AWS Lambda など）で、ステートレスモードを有効にするために使用します。

プロパティ	型	デフォルト	説明
serverless	boolean	false	セッション管理を行わず、MCP をステートレスモードで実行します。
sessionIdGenerator	() => string	undefined	カスタムセッション ID 生成関数。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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

server.build

サーバー機能のビルド時設定です。これらのオプションでは、ローカル開発中は有効で、本番環境ではデフォルトで無効になる Swagger UI やリクエストログなどの開発 Tool を制御します。

プロパティ	型	デフォルト	説明
swaggerUI	boolean	false	対話的な API 調査のため、/swagger-ui で Swagger UI を有効にします（openAPIDocs が true である必要があります）。
apiReqLogs	boolean	false	API リクエストのコンソールへのログ記録を有効にします。
openAPIDocs	boolean	false	/api/openapi.json で OpenAPI 仕様を有効にします。Mastra の組み込みルートは servers: [{url: "/api"}] を使用し、カスタムルートにはパスごとに servers: [{url: "/"}] の上書きが設定されます。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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

server.cors

型： CorsOptions | false

サーバーの CORS（Cross-Origin Resource Sharing）設定です。CORS を完全に無効化するには、false に設定します。すべてのルートに1つのポリシーを適用する場合に使用します。カスタムルート固有のポリシーには、registerApiRoute() の cors オプションを使用してください。

プロパティ	型	デフォルト	説明
origin	string | string[]	'*'	CORS リクエストの Origin。
allowMethods	string[]	['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']	HTTP メソッド。
allowHeaders	string[]	['Content-Type', 'Authorization', 'x-mastra-client-type', 'x-mastra-dev-playground']	リクエストヘッダー。
exposeHeaders	string[]	['Content-Length', 'X-Requested-With']	ブラウザーへ公開するヘッダー。
credentials	boolean	false	認証情報（Cookie、Authorization ヘッダー）。
maxAge	number	3600	プリフライトリクエストのキャッシュ期間（秒）。

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

型： string
デフォルト： localhost（MASTRA_HOST 環境変数が設定されている場合は、その値）

Mastra 開発サーバーがバインドするホストアドレスです。MASTRA_HOST 環境変数が設定されている場合は、デフォルトより優先されます。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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

server.https

型： { key: Buffer; cert: Buffer }

TLS を使用して開発サーバーを実行するための HTTPS 設定です。Mastra は mastra dev --https フラグによるローカル HTTPS 開発をサポートし、証明書を自動的に作成して管理します。証明書を独自に管理する場合は、次のように鍵ファイルと証明書ファイルを指定します。

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

型： Middleware | Middleware[]

ルートハンドラーの前後でリクエストをインターセプトするカスタム Middleware 関数です。Middleware は、認証、ログ記録、リクエスト固有のコンテキストの注入、ヘッダーの追加に使用できます。各 Middleware は Hono の Context と next 関数を受け取ります。リクエストの処理をそこで終了するには Response を返し、処理を続行するには next() を呼び出します。

詳しくは、Middleware のドキュメントを参照してください。

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

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

未処理のエラーが発生したときに呼び出されるカスタムエラーハンドラーです。エラー応答のカスタマイズ、Sentry などの外部サービスへのエラー記録、カスタムエラー形式の実装に使用します。

この Hook は、すべての Server Adapter でサポートされています。c パラメーターは Hono 互換のコンテキストオブジェクトを提供します。Hono 以外の Adapter（Koa、Express、Fastify）では、c.json() や c.req.path など、よく使用されるメソッドを備えた shim が提供されます。

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

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

リクエストが Zod スキーマのバリデーションに失敗したときに呼び出されるカスタムハンドラーです。バリデーションエラー応答のカスタマイズ、ステータスコードの変更、API 標準に合わせたエラー形式の調整に使用します。

デフォルトの 400 応答を上書きするには { status, body } オブジェクトを返し、デフォルトの動作を使用するには undefined を返します。この Hook は、すべての Server Adapter（Hono、Express、Fastify、Koa）でサポートされています。

context パラメーターは、リクエストのどの部分がバリデーションに失敗したかを示します。

• 'query'：クエリパラメーター
• 'body'：リクエストボディ
• 'path'：パスパラメーター

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,
      },
    }),
  },
})

createRoute() で作成した個別のルートにも onValidationError を設定できます。ルートレベルの Hook は、サーバーレベルの Hook より優先されます。

server.port

型： number
デフォルト： 4111（PORT 環境変数が設定されている場合は、その値）

Mastra 開発サーバーがバインドするポートです。PORT 環境変数が設定されている場合は、デフォルトより優先されます。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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

server.studioBase

型： string
デフォルト： /

Studio をホストするベースパスです。既存アプリケーションのルートではなく、サブパスで Studio をホストする場合に使用します。

これは、既存アプリケーションとの統合、共有ドメインが適する Cloudflare Zero Trust などの認証 Tool の使用、単一ドメインでの複数サービスの管理に便利です。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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

URL の例：

• デフォルト：http://localhost:4111/（ルートに Studio）
• studioBase を指定：http://localhost:4111/my-mastra-studio/（サブパスに Studio）

server.timeout

型： number
デフォルト： 180000（3分）

リクエストのタイムアウト（ミリ秒）です。この時間を超えたリクエストは終了します。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

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