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

# Server Adapter

Server Adapter を使用すると、`mastra build` が生成する Hono サーバーの代わりに、独自の HTTP サーバーで Mastra を実行できます。カスタムミドルウェアの順序、認証、ログ記録、デプロイ設定など、サーバーのセットアップをより細かく制御できます。Agent や Workflow の実行方法を変更することなく、Mastra を任意の Node.js アプリケーションに統合できます。

> **警告:** Server Adapter は渡された `mastra` インスタンスを使用し、ファイルベースの検出は実行しません。そのインスタンスにコードで Agent を登録してください。ファイルベースの Agent を使用するには、`mastra dev` または `mastra build` で Mastra を別のサーバーとして実行します。

## Server Adapter を使用する場面

- 既存のアプリケーションに Mastra のエンドポイントを自動的に追加したい場合
- カスタム設定のためにサーバーインスタンスへ直接アクセスする必要がある場合
- `mastra build` が作成する Hono サーバーではなく、別のサーバーフレームワークをチームで使用したい場合

> **ヒント:** サーバーにカスタム要件がないデプロイでは、代わりに `mastra build` を使用してください。サーバーのセットアップとミドルウェアの登録を行い、プロジェクト設定に基づいてデプロイ設定も適用します。詳しくは、[サーバー設定](https://mastra.zisheng.pro/ja/docs/server/mastra-server)を参照してください。
>
> Server Adapter で [Studio](https://mastra.zisheng.pro/ja/docs/studio/overview) を使用する場合は、[`mastra studio`](https://mastra.zisheng.pro/ja/reference/cli/mastra) を使用して Studio UI だけを起動してください。

## 利用可能な Adapter

Mastra は現在、次の公式 Server Adapter を提供しています。

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

独自の Adapter も構築できます。詳しくは、[カスタム Adapter](https://mastra.zisheng.pro/ja/docs/server/custom-adapters)を参照してください。

## インストール

使用するフレームワークの Adapter をインストールします。

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

## 設定

通常どおりアプリを初期化してから、`MastraServer` を作成し、`app` とメインの `mastra` インスタンス（`src/mastra/index.ts` から取得）を渡します。`init()` を呼び出すと、Mastra のミドルウェアと利用可能なすべてのエンドポイントが自動的に登録されます。`init()` の前後どちらでも、通常どおり独自のルートを追加でき、それらは 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')
})
```

すべての設定オプションについては、[Express Adapter](https://mastra.zisheng.pro/ja/reference/server/express-adapter) のドキュメントを参照してください。

**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')
})
```

すべての設定オプションについては、[Hono Adapter](https://mastra.zisheng.pro/ja/reference/server/hono-adapter) のドキュメントを参照してください。

**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`)
})
```

すべての設定オプションについては、[Fastify Adapter](https://mastra.zisheng.pro/ja/reference/server/fastify-adapter) のドキュメントを参照してください。

**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`)
})
```

すべての設定オプションについては、[Koa Adapter](https://mastra.zisheng.pro/ja/reference/server/koa-adapter) のドキュメントを参照してください。

**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()
```

すべての設定オプションについては、[NestJS Adapter](https://mastra.zisheng.pro/ja/reference/server/nestjs-adapter) のドキュメントを参照してください。

## 初期化フロー

`init()` を呼び出すと、次の3つのステップが順番に実行されます。このフローを理解しておくと、特定の位置に独自のミドルウェアを挿入する場合に役立ちます。

1. `registerContextMiddleware()`: Mastra インスタンス、Request Context、Tool、AbortSignal をすべてのリクエストに付加します。これにより、後続のすべてのミドルウェアとルートハンドラーで Mastra を使用できます。
2. `registerAuthMiddleware()`: 初期化中に Adapter の認証フックを実行します。公式 Adapter は、Mastra が組み込みルートと `registerApiRoute()` のルートを登録する際にインラインで認証を適用します。そのため、生のフレームワークルートで Mastra の認証が必要な場合は、Adapter がエクスポートする `createAuthMiddleware()` ヘルパーを使用してください。
3. `registerRoutes()`: Agent、Workflow、その他の機能に対応する Mastra API ルートをすべて登録します。MCP サーバーが設定されている場合は、MCP ルートも登録します。

### 手動での初期化

ミドルウェアの順序をカスタマイズするには、`init()` の代わりに各メソッドを個別に呼び出します。Mastra のコンテキストが設定される前に実行するミドルウェアが必要な場合や、初期化ステップの間にロジックを挿入する必要がある場合に便利です。

```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', ...);
```

> **ヒント:** Mastra のコンテキストが利用可能になる前に実行するミドルウェアが必要な場合や、コンテキストと認証のステップの間にミドルウェアを挿入する必要がある場合は、手動で初期化してください。

## カスタムルートの追加

Mastra のルートと並行して、独自のルートをアプリに追加できます。

- `init()` の**前**に追加したルートでは、Mastra のコンテキストを利用できません。
- `init()` の**後**に追加したルートでは、Mastra のコンテキスト（Mastra インスタンス、Request Context、認証済みユーザーなど）へアクセスできます。
- Mastra が管理する認証と `requiresAuth` などのルートメタデータを使用する場合は、`registerApiRoute()` を推奨します。
- フレームワークのアプリにルートを直接マウントする場合、そのルートで Mastra の認証が必要なら、Adapter がエクスポートする `createAuthMiddleware()` ヘルパーを使用してください。

詳しくは、Express と Hono の「カスタムルートの追加」を参照してください。[Express](https://mastra.zisheng.pro/ja/reference/server/express-adapter)、[Hono](https://mastra.zisheng.pro/ja/reference/server/hono-adapter)

## ルートのプレフィックス

デフォルトでは、Mastra のルートは `/api/agents`、`/api/workflows` などに登録されます。これを変更するには `prefix` オプションを使用します。API のバージョニングや、独自の `/api` ルートを持つ既存アプリとの統合に便利です。

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

このプレフィックスを設定すると、Mastra のルートは `/api/v2/agents`、`/api/v2/workflows` などになります。アプリに直接追加したカスタムルートは、このプレフィックスの影響を受けません。

## OpenAPI 仕様

Mastra は、登録済みのすべてのルートに対する OpenAPI 仕様を生成できます。ドキュメント、クライアント生成、API Tool との統合に便利です。`openapiPath` オプションを設定して有効にします。

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

仕様は各ルートに定義された Zod スキーマから生成され、指定したパスで提供されます。Mastra のすべてのルートに加え、`createRoute()` で作成したカスタムルートも含まれます。

## ストリームデータの秘匿化

Agent のレスポンスを HTTP 経由でストリーミングする際、HTTP ストリーミングレイヤーはクライアントへ送信する前に、ストリームのチャンクから機密情報を秘匿します。これにより、次の情報が誤って公開されるのを防ぎます。

- システムプロンプトと Agent の指示
- Tool の定義とそのパラメーター
- リクエスト本文内の API キーやその他の認証情報
- 内部設定データ

この秘匿化は HTTP 境界で行われるため、`onStepFinish` などの内部コールバックでは、デバッグや可観測性のために引き続き完全なリクエストデータへアクセスできます。

デフォルトでは秘匿化が有効です。この動作は `streamOptions` で設定します。ストリームレスポンス内の完全なリクエストデータへアクセスする必要がある内部サービスやデバッグ用途に限り、`redact: false` を設定してください。

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

すべての設定オプションについては、[MastraServer](https://mastra.zisheng.pro/ja/reference/server/mastra-server) を参照してください。

## ルート単位での認証の上書き

Mastra インスタンスに認証が設定されている場合、デフォルトではすべてのルートで認証が必要です。ただし、公開するヘルスチェックエンドポイントや Webhook 受信エンドポイント、より厳格な制御が必要な管理ルートなど、例外が必要になることがあります。

特定のルートの認証動作を上書きするには、`customRouteAuthConfig` を使用します。キーは `METHOD:PATH` 形式で、メソッドには `GET`、`POST`、`PUT`、`DELETE`、`ALL` を指定できます。パスでは、複数のルートに一致させるためにワイルドカード（`*`）を使用できます。値を `false` に設定するとルートが公開され、`true` に設定すると認証が必須になります。

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

すべての設定オプションについては、[MastraServer](https://mastra.zisheng.pro/ja/reference/server/mastra-server) を参照してください。

## アプリへのアクセス

Adapter の作成後も、基盤となるフレームワークのアプリへアクセスする必要がある場合があります。プラットフォームの `serve` 関数へ渡す場合や、別のモジュールからルートを追加する場合に便利です。

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

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

どちらのメソッドも同じアプリインスタンスを返します。スコープ内で利用できるものに応じて、使いやすい方を使用してください。

## サーバー設定と Adapter オプションの違い

Server Adapter を使用する場合、設定は2か所から取得されます。Mastra の `server` 設定（`Mastra` コンストラクターに渡すもの）と、Adapter のコンストラクターオプションです。各オプションの取得元を理解しておくと、設定が反映されない場合の混乱を避けられます。

### Adapter が使用する設定

Adapter は `mastra.getServer()` から次の設定を読み取ります。

| オプション           | 説明                                                                                                                            |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `auth`          | `registerAuthMiddleware()` で使用する認証設定。                                                                                         |
| `bodySizeLimit` | バイト単位のデフォルトの本文サイズ制限。Adapter ごとに `bodyLimitOptions` で上書きできます。                                                                  |
| `onError`       | ルートハンドラーで未処理のエラーが発生したときに呼び出されるカスタムエラーハンドラー。[server.onError](https://mastra.zisheng.pro/ja/reference/configuration) を参照してください。 |

### Adapter のコンストラクター専用

次のオプションは Adapter のコンストラクターへ直接渡され、Mastra の設定からは読み取られません。

| オプション                   | 説明                                                  |
| ----------------------- | --------------------------------------------------- |
| `prefix`                | ルートパスのプレフィックス                                       |
| `openapiPath`           | OpenAPI 仕様のエンドポイント                                  |
| `bodyLimitOptions`      | カスタムエラーハンドラーを伴う本文サイズ制限                              |
| `streamOptions`         | ストリームの秘匿化設定                                         |
| `customRouteAuthConfig` | ルート単位での認証の上書き                                       |
| `mcpOptions`            | MCP トランスポートオプション（ステートレス環境向けの `serverless: true` など） |

### Adapter が使用しない設定

次の `server` 設定オプションは `mastra build` だけが使用し、Adapter を直接使用する場合は効果がありません。

| オプション          | 使用箇所                                    |
| -------------- | --------------------------------------- |
| `port`, `host` | `mastra dev`、`mastra build`             |
| `cors`         | `mastra build` が CORS ミドルウェアを追加         |
| `timeout`      | `mastra build`                          |
| `apiRoutes`    | `registerApiRoute()`（`mastra build` 向け） |
| `middleware`   | `mastra build` のミドルウェア設定                |

Adapter を使用する場合、これらの機能はフレームワークで直接設定してください。たとえば、Hono または Express の組み込み CORS パッケージを使用して CORS ミドルウェアを追加し、フレームワークの listen 関数を呼び出す際にポートを設定します。

## MCP のサポート

Mastra インスタンスに MCP サーバーが設定されている場合、Server Adapter は `registerRoutes()` の実行時に MCP（Model Context Protocol）ルートを登録します。MCP を使用すると、外部の Tool やサービスが Mastra サーバーへ接続し、Agent とやり取りできます。

Adapter は HTTP と SSE（Server-Sent Events）の両方のトランスポートに対応するルートを登録し、異なるクライアント接続パターンを利用できるようにします。

### Serverless モード

Cloudflare Workers や Vercel Edge などの Serverless 環境では、`mcpOptions` でステートレスモードを有効にします。

Mastra Deployer（標準の `mastra dev` / `mastra build` のパス）を使用する場合は、サーバー設定で `mcpOptions` を設定します。

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

Server Adapter を手動で作成する場合は、`mcpOptions` を直接渡します。

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

`serverless: true` の場合、MCP HTTP リクエストはセッション管理なしで実行されるため、ステートレスな実行環境と互換性があります。

設定の詳細と MCP サーバーのセットアップ方法については、[MCP](https://mastra.zisheng.pro/ja/docs/mcp/overview) を参照してください。

## 関連項目

- [Hono Adapter](https://mastra.zisheng.pro/ja/reference/server/hono-adapter) - Hono 固有のセットアップ
- [Express Adapter](https://mastra.zisheng.pro/ja/reference/server/express-adapter) - Express 固有のセットアップ
- [NestJS Adapter](https://mastra.zisheng.pro/ja/reference/server/nestjs-adapter) - NestJS 固有のセットアップ
- [カスタム Adapter](https://mastra.zisheng.pro/ja/docs/server/custom-adapters) - その他のフレームワーク向けの Adapter の構築
- [サーバー設定](https://mastra.zisheng.pro/ja/docs/server/mastra-server) - 代わりに `mastra build` を使用する方法
- [認証](https://mastra.zisheng.pro/ja/docs/server/auth) - サーバーの認証設定
- [MastraServer リファレンス](https://mastra.zisheng.pro/ja/reference/server/mastra-server) - API リファレンスの全内容
- [createRoute() リファレンス](https://mastra.zisheng.pro/ja/reference/server/create-route) - 型安全なカスタムルートの作成