Express アダプター

@mastra/express パッケージは、Express で Mastra を実行するための Server アダプターを提供します。一般的なアダプターの概念（コンストラクターオプション、初期化フローなど）については、Server アダプターを参照してください。

インストール

Express アダプターと Express フレームワークをインストールします。

npm

npm install @mastra/express@latest express

pnpm

pnpm add @mastra/express@latest express

Yarn

yarn add @mastra/express@latest express

Bun

bun add @mastra/express@latest express

使用例

server.ts

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

const app = express()
app.use(express.json()) // Required for body parsing

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

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

注記

Express で JSON リクエストボディを解析するには、express.json() ミドルウェアが必要です。MastraServer を作成する前に追加してください。

コンストラクターパラメーター

app:

Application

Express アプリのインスタンス

mastra:

Mastra

Mastra インスタンス

prefix?:

string

= ''

ルートパスのプレフィックス（例: /api/v2）

openapiPath?:

string

= ''

OpenAPI 仕様を配信するパス（例: /openapi.json）

bodyLimitOptions?:

{ maxSize: number, onError: (err) => unknown }

リクエストボディのサイズ上限

streamOptions?:

{ redact?: boolean }

= { redact: true }

Stream の機密情報をマスキングする設定。true の場合、Stream から機密データをマスキングします。

customRouteAuthConfig?:

Map<string, boolean>

ルートごとの認証設定の上書き。キーは METHOD:PATH（例: GET:/api/health）です。値が false の場合はルートを公開し、true の場合は認証を必須にします。

tools?:

Record<string, Tool>

Server で使用できる Tool

taskStore?:

InMemoryTaskStore

A2A（Agent-to-Agent）操作用のタスクストア

mcpOptions?:

MCPOptions

MCP トランスポートオプション。Cloudflare Workers や Vercel Edge などのステートレス環境では serverless: true を設定します。

Hono との違い

項目	Express	Hono
ボディの解析	express.json() が必要	フレームワークが処理
コンテキストの保存	res.locals	c.get() / c.set()
ミドルウェアのシグネチャ	(req, res, next)	(c, next)
Streaming	res.write() / res.end()	stream() ヘルパー
AbortSignal	req.on('close') から作成	c.req.raw.signal

カスタムルートの追加

Express アプリにルートを直接追加します。

server.ts

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

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

// Before init - runs before Mastra middleware
app.get('/early-health', (req, res) => res.json({ status: 'ok' }))

await server.init()

// After init - has access to Mastra context
app.get('/custom', (req, res) => {
  const mastraInstance = res.locals.mastra
  res.json({ agents: Object.keys(mastraInstance.listAgents()) })
})

app.listen(4111)

ヒント

init() より前に追加したルートは、Mastra コンテキストなしで実行されます。Mastra インスタンスとリクエストコンテキストにアクセスするには、init() より後にルートを追加してください。

Mastra が管理する認証と requiresAuth などのルートメタデータを使用する場合は、registerApiRoute() を推奨します。app に直接マウントする素の Express ルートでは、createAuthMiddleware() を使用します。

server.ts

import express from 'express'
import { createAuthMiddleware, 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.get('/custom/protected', createAuthMiddleware({ mastra }), (req, res) => {
  const user = res.locals.requestContext.get('user')
  res.json({ user })
})

app.get('/custom/public', createAuthMiddleware({ mastra, requiresAuth: false }), (req, res) => {
  res.json({ ok: true })
})

コンテキストへのアクセス

Express のミドルウェアとルートでは、res.locals を介して Mastra コンテキストにアクセスします。

app.get('/custom', (req, res) => {
  const mastra = res.locals.mastra
  const requestContext = res.locals.requestContext
  const abortSignal = res.locals.abortSignal

  const agent = mastra.getAgent('myAgent')
  res.json({ agent: agent.name })
})

res.locals では、次のプロパティを使用できます。

キー	説明
mastra	Mastra インスタンス
requestContext	リクエストコンテキストのマップ
abortSignal	リクエストのキャンセルシグナル
tools	使用可能な Tool
taskStore	A2A 操作用のタスクストア
customRouteAuthConfig	ルートごとの認証設定の上書き
user	認証済みユーザー（認証が設定されている場合）

ミドルウェアの追加

Express ミドルウェアは、init() の前または後に追加します。

server.ts

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

// Middleware before init
app.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`)
  next()
})

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

// Middleware after init has access to Mastra context
app.use((req, res, next) => {
  const mastra = res.locals.mastra
  next()
})

手動初期化

ミドルウェアの順序をカスタマイズするには、init() の代わりに各メソッドを個別に呼び出します。詳細については、手動初期化を参照してください。

例

• Express アダプター: Express Server の基本的なセットアップ

関連項目

• Server アダプター: アダプター共通の概念
• MastraServer リファレンス: 完全な API リファレンス
• createRoute() リファレンス: 型安全なカスタムルートの作成