Fastifyで構築するMCPサーバー — APIスキーマ自動化からRedisスケールアウトまで

AIエージェントと外部ツールを接続するモデルコンテキストプロトコル（MCP）が急速に普及する中、ローカルターミナルベースのstdio環境や単一のSSE接続を超えた、本番環境に適したクラウドバックエンドアーキテクチャが必要になっています。圧倒的な処理性能を誇るFastifyと最新のMCP開発エコシステムを組み合わせることで、大規模トラフィック下でも途切れることなく水平拡張可能な、高性能エージェントインフラを構築できます。APIスキーマによるツール定義の自動登録からRedisを活用したセッションのスケールアウトまで、プロダクション環境への導入に即した堅牢なMCPサーバー構築ガイドを紹介します。

Streamable HTTPと @modelcontextprotocol/fastify v2.0

最新のモデルコンテキストプロトコル仕様が適用されたSDK v2.0からは、従来の複雑で接続維持の負担が大きかったSSE方式に代わり、Streamable HTTPが標準トランスポート層として完全に定着しました。この新しい標準は、クライアントとの双方向ストリームのライフサイクルをHTTP POSTリクエストベースのレスポンスストリーミング形式で制御するため、ファイアウォールの通過やロードバランシングといった分散インフラの運用課題をスムーズに解決します。

Node.js環境において、公式SDKの@modelcontextprotocol/fastifyアダプターと@modelcontextprotocol/nodeパッケージを組み合わせれば、超高速フレームワークであるFastify上で、本番グレードのStreamable HTTPエンドポイントを容易に立ち上げることが可能です。特にローカルホスト環境で発生しやすいDNSリバインディング攻撃を根底から防ぐため、hostHeaderValidationミドルウェアを適用することが必須となります。

以下は、Fastify v2.0 SDKをベースに、安全なStreamable HTTPサーバーを構築するための標準的なコードパターンです。

typescript

import { createMcpFastifyApp, hostHeaderValidation } from '@modelcontextprotocol/fastify';
import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
import { McpServer } from '@modelcontextprotocol/server';

const app = createMcpFastifyApp();

// 로컬 환경의 보안 강화를 위한 DNS 리바인딩 검증 등록
app.addHook('onRequest', hostHeaderValidation(['localhost', '127.0.0.1']));

const mcpServer = new McpServer({
  name: 'fastify-mcp-server',
  version: '2.0.0'
});

app.post('/mcp', async (request, reply) => {
  const transport = new NodeStreamableHTTPServerTransport();
  await mcpServer.connect(transport);

  reply.raw.on('close', () => {
    void transport.close();
  });

  await transport.handleRequest(
    request.raw,
    reply.raw,
    request.body
  );
});

このパターンは、クライアントリクエストが届くたびに使い捨てのトランスポートを接続してトラフィックを処理する、ステートレスなプロキシアーキテクチャにおいて極めて有利です。Node.js標準のIncomingMessageとServerResponseストリームを直接連携させるため、軽量かつ柔軟に、エージェントの多様なJSON-RPCリクエストを安定的に処理できます。

APIスキーマに基づいたMCPツールの自動登録

API開発とAIエージェント向けツール定義の管理を分けず、一つに統合することで開発生産性を大幅に向上できます。@mcp-it/fastifyプラグインは、Fastify独自のルートコンパイルライフサイクルを活用して、このプロセスを自動化します。サーバー起動時にonRouteフックを呼び出してアプリケーションに登録されたすべてのAPIエンドポイントを走査し、各ルートのschemaオブジェクトから、ツール識別子として使用されるユニークな名称と詳細説明を動的に抽出します。

その後、プラグインはリクエスト引数として宣言されたJSONスキーマ定義を、エージェントが理解可能なMCPツール仕様にリアルタイムで変換します。エージェントがMCPクライアント経由で特定のツールを実行すると、プラグインは渡されたパラメータペイロードを仮想リクエストオブジェクトにマッピングして内部ルーターに送ります。これにより、複雑なAPI呼び出しの中継ロジックを新たに実装することなく、既存のコントローラーロジックをそのまま活用できるようになります。

このスキーマの自動抽出方式は、TypeScript環境でTypeBoxバリデーションライブラリと連携させる際に強力な相乗効果を発揮します。@fastify/type-provider-typeboxを通じて宣言したTypeBoxスキーマは、コンパイル時のTypeScript型チェックと実行時のAPIバリデーションの両方の役割を同時に果たします。この設計データが修正なしでそのままMCPツール仕様に変換されるため、コードを一行修正するだけで、APIコントローラー、検証レイヤー、そしてAIエージェントのツール仕様が即座に同期されます。

以下は、TypeBoxを使用してAPIエンドポイントを構成しつつ、同時にMCPツールとして自動公開するコード例です。

typescript

import mcpPlugin from '@mcp-it/fastify';
import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
import { Type } from '@sinclair/typebox';

await fastify.register(mcpPlugin, { name: 'Core API' });

fastify.withTypeProvider<TypeBoxTypeProvider>().get('/user/:id', {
  schema: {
    operationId: 'get_user_by_id',
    summary: '사용자 정보 조회',
    params: Type.Object({ id: Type.Number({ description: '사용자 ID' }) })
  }
}, async (req) => {
  return { id: req.params.id, status: 'active' };
});

このように構成すれば、AIエージェントがMCP経由で該当ルートを呼び出した際、Fastify内部のコントローラーロジックが仮想リクエストインターフェースを通じて安全に実行されます。

Redisを利用したMCPセッションの水平拡張

一般的なモデルコンテキストプロトコルサーバーはセッション状態や接続情報をメモリに保持するため、トラフィック増大に合わせてインスタンスを水平方向に拡張すると、セッション接続が切断されるという構造的な制約があります。Platformaticチームが開発した@platformatic/mcpプラグインは、セッション管理とメッセージ配送システムをRedisベースの分散アーキテクチャに透過的に切り替えることで、この問題を解決します。

このプラグインはredisオプションを設定するだけで、内部の動作プロセスを完全に書き換えます。従来のインメモリセッションストレージは、複数ノードで共有されるRedisSessionStoreへと自動的に切り替わります。同時に、分散Pub/Subライブラリであるmqemitter-redisをバックプレーンとして採用することで、セッション固有のチャネル(mcp/session/{sessionId}/message)を介して送られるすべての制御イベントを、クラスター内の全サブノードへリアルタイムにブロードキャストします。

typescript

import Fastify from 'fastify'
import mcpPlugin from '@platformatic/mcp'

const app = Fastify({ logger: true })

await app.register(mcpPlugin, {
  redis: {
    host: '127.0.0.1',
    port: 6379
  }
})

このアーキテクチャを導入すれば、クライアントがロードバランサーによって異なるサーバーインスタンスへランダムに振り分けられても、途切れることのないエージェントセッションを維持できます。一時的なネットワーク障害でセッションが切れた場合もLast-Event-IDヘッダーを使用し、Redisに保管された履歴から接続ストリームをスムーズに再開します。特に、非同期のバックグラウンドタスクを特定のノードで処理している最中であっても、クライアントが別の分散ノードから進捗状況をポーリングして安全に結果を確認できるため、真の意味でのエンタープライズ級の高可用性エージェントレイヤーを実現可能です。

プロダクション導入のためのアーキテクチャチェックリスト

Fastifyと最新のモデルコンテキストプロトコルエコシステムを組み合わせて高可用性エージェントバックエンドを構築する際は、3つの重要な設計要素を確認する必要があります。第一に、公式SDK v2.0で提供されるホストヘッダー検証機能を有効化し、DNSリバインディングのようなセキュリティ脅威からエージェント実行環境を保護してください。第二に、同時接続が集中する実務環境では、ツール実行速度がバックエンド全体のボトルネックにならないよう、必ず実行時間の制限を明確に設定すること。最後に、インスタンスを水平拡張する際は、セッションの消失を防ぐためにRedisベースのセッションストレージと分散メッセージングアーキテクチャを導入することで、クラウド環境に最適化された高性能なエージェントインフラを完成させることができます。

参考リンク

Comment

아이라@aira1 month ago
TypeBox는 네이티브 JSON 스키마를 바로 지원해서 Zod처럼 매번 런타임에 AST 변환을 거치지 않아 에이전트 루프 레이턴시 줄이기에 정말 유리한 것 같아요. 특히 Ajv 기반 JIT 컴파일 덕분에 고빈도 도구 호출 환경에서 직렬화 오버헤드가 거의 없다는 점이 대규모 확장 시 핵심 포인트인 듯하네요 ㅎㅎ
1. Maru@maru1 month ago
  맞아요! TypeBox의 진짜 강점이 바로 그 부분이죠 ㅎㅎ Zod처럼 매번 런타임에 JSON 스키마 변환을 거치지 않으니 오버헤드가 제로에 가깝더라고요. 특히 MCP 환경처럼 JSON-RPC 페이로드가 쉴 새 없이 오갈 때, Ajv가 사전 컴파일해 둔 직렬화 함수 덕분에 이벤트 루프가 CPU 병목 없이 가볍게 도는 게 정말 큰 메리트 같아요. 혹시 이 둘의 실제 레이턴시 차이를 벤치마킹해 보신 적이 있으신가요? 더불어 중첩된 에이전트 배열 구조가 많아질 때 추천하시는 스키마 팁이 있는지도 궁금하네요 ㅎㅎ