サーバーの概要

Mastra は HTTP サーバーとして動作し、Agent、Workflow、その他の機能を API エンドポイントとして公開します。サーバーはリクエストのルーティング、ミドルウェアの実行、認証、ストリーミングレスポンスを処理します。

情報

このページでは、Mastra コンストラクターに渡す server 設定オプションを説明します。独自の HTTP サーバー（Hono、Express など）で Mastra を実行する方法については、Server Adapter を参照してください。

サーバー機能

• ミドルウェア: 認証、ログ記録、CORS、リクエスト固有のコンテキスト注入のためにリクエストをインターセプトします。
• カスタム API ルート: Mastra インスタンスへアクセスできる独自の HTTP エンドポイントでサーバーを拡張します。
• Request Context: 実行時の条件に基づき、リクエスト固有の値を Agent、Tool、Workflow に渡します。
• Server Adapter: 生成されたサーバーの代わりに、Express、Hono、または独自の HTTP サーバーで Mastra を実行します。
• カスタム Adapter: 公式にはサポートされていないフレームワーク向けの Adapter を構築します。
• Mastra Client SDK: ブラウザまたはサーバー環境から Agent、Workflow、Tool を呼び出すための型安全なクライアントです。
• A2A: A2A Agent カード、タスクストリーム、プッシュ通知を通じて Agent を公開します。
• 認証: JWT、Clerk、Supabase、Firebase、Auth0、WorkOS でエンドポイントを保護します。

設定

Mastra コンストラクターに server オブジェクトを渡してサーバーを設定します。

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    port: 3000, // Defaults to PORT env var or 4111
    host: '0.0.0.0', // Defaults to MASTRA_HOST env var or 'localhost'
  },
})

利用可能なサーバーオプションの全一覧については、設定リファレンスを参照してください。

サーバーのデプロイ

Mastra サーバーは、Node.js と互換性のあるあらゆる環境にデプロイできます。Mastra platform または独自のインフラストラクチャを使用して本番環境へデプロイしてください。方法については、デプロイメントドキュメントを参照してください。

サーバーアーキテクチャ

Mastra は基盤となる HTTP サーバーフレームワークとして Hono を使用します。mastra build で Mastra アプリケーションをビルドすると、.mastra ディレクトリに Hono ベースの HTTP サーバーが生成されます。

サーバーは次の機能を提供します。

• 登録済みのすべての Agent と Workflow の API エンドポイント
• カスタム API ルートとミドルウェア
• 複数の Provider にわたる認証
• 実行時設定用の Request Context
• 安全なレスポンスのためのストリームデータ秘匿化

REST API

http://localhost:4111/api/openapi.json の OpenAPI 仕様では、利用可能なすべてのエンドポイントと各リクエスト・レスポンススキーマを確認できます。

API を対話的に確認するには、http://localhost:4111/swagger-ui の Swagger UI を開きます。ブラウザからエンドポイントを探して直接テストできます。

注記

本番環境では、OpenAPI と Swagger のエンドポイントはデフォルトで無効です。有効にするには、server.build.openAPIDocs と server.build.swaggerUI をそれぞれ true に設定します。

OpenAI Responses API

Mastra は OpenAI 互換の Responses ルートと Conversations ルートを公開し、Mastra Agent を Responses API として使用できるようにします。これらのルートは Mastra の Agent、Memory、ストレージを基盤とする Adapter です。リクエストは Provider への単純なプロキシではなく、選択した Mastra Agent を通じて実行されます。

これらの API は現在実験的な機能です。

リクエストを処理する Mastra Agent は agent_id で選択します。最初のリクエストは Agent を直接対象とし、保存された後続のターンは previous_response_id で継続できます。model を渡して、1回のリクエストに限り Agent に設定されたモデルを上書きすることもできます。model を省略すると、Mastra は Agent に設定済みのモデルを使用します。

Responses ルートは、ストリーミング、関数呼び出し（Tool）、previous_response_id による保存済みの継続、conversation_id による会話スレッド、providerOptions による Provider 固有のパススルー、text.format による JSON 出力をサポートします。

リクエストとレスポンスの完全な仕様については、Responses API リファレンスとConversations API リファレンスを参照してください。HTTP ルートの全一覧については、サーバールートを参照してください。

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

Agent のレスポンスをストリーミングする際、HTTP レイヤーはクライアントへ送信する前に、各チャンクからシステムプロンプト、Tool 定義、API キーなどのデータを秘匿します。この機能はデフォルトで有効です。

この動作を設定できるのは、Server Adapter を使用する場合だけです。Server Adapter でも、ストリームデータの秘匿化はデフォルトで有効です。

TypeScript の設定

Mastra には、最新の Node.js と互換性のある module および moduleResolution 設定が必要です。CommonJS や node などの従来のオプションはサポートされていません。

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

次のステップ

• ミドルウェアを追加する
• カスタム API ルートを作成する
• 認証を追加する
• サーバーを本番環境へデプロイする