FastifyのAgenticミドルウェア — 手動実装不要のMCP v2.0バックエンドパターン

Model Context Protocol (MCP) v2.0仕様がステートレスなHTTP標準を採用したことで、AIエージェントとバックエンドAPIを接続する方法が転換期を迎えています。これまでは、LLMが呼び出すツールを開発者が都度加工し、複雑なルーティングルールを一つひとつ手作業で管理する必要がありました。しかし現在、Fastifyエコシステムは公式アダプターや高性能プラグインを活用し、ステートレスな分散処理やセキュリティ検証を自動化する「Agenticミドルウェア」パターンへと急速に進化しています。

公式 @modelcontextprotocol/fastifyアダプターの導入

公式 @modelcontextprotocol/fastify パッケージは、Fastifyアプリケーション上でMCP仕様に準拠したツールをホスティングするための最適な専用アダプターです。このアダプターは、ステートレス環境で不可欠なDNSリバインディング保護やHostヘッダー検証を、Fastify固有の高性能なライフサイクル内で自然に処理します。特に2026年7月に発表されたMCP v2.0仕様を完全にサポートするため、モノリシックな構造を脱却し、軽量なモジュールへとリファクタリングされました。

以下は、@modelcontextprotocol/server および関連パッケージのv2.0.0を適用して構築した、高性能なステートレスMCPサーバーの実装例です。

import { createMcpFastifyApp } from '@modelcontextprotocol/fastify';
import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
import { McpServer } from '@modelcontextprotocol/server';
import { z } from 'zod';

const app = createMcpFastifyApp();
const mcpServer = new McpServer({
  name: 'my-agent-tools',
  version: '2.0.0',
});

// v2.0.0 규격의 registerTool API 사용
mcpServer.registerTool(
  'calculate',
  {
    description: '두 숫자의 사칙연산을 수행합니다.',
    inputSchema: z.object({
      a: z.number(),
      b: z.number(),
      operator: z.enum(['add', 'subtract', 'multiply', 'divide']),
    }),
  },
  async ({ a, b, operator }) => {
    let result = 0;
    if (operator === 'add') result = a + b;
    else if (operator === 'subtract') result = a - b;
    else if (operator === 'multiply') result = a * b;
    else if (operator === 'divide') result = a / b;

    return {
      content: [{ type: 'text', text: String(result) }],
    };
  }
);

// 무상태 HTTP 라우트 등록
app.post('/mcp', async (request, reply) => {
  const transport = new NodeStreamableHTTPServerTransport({
    sessionIdGenerator: undefined, // 무상태 모드 활성화
  });

  await mcpServer.connect(transport);

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

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

await app.listen({ port: 3000 });

この構造を採用すれば、複雑なセッション維持なしで個々のHTTPリクエストを独立して処理できるため、分散サーバー環境におけるリソースの最大化と柔軟な水平スケーリングが可能になります。

@platformatic/mcpを活用したエンタープライズ級の拡張性

単一インスタンス環境を超え、マルチテナントやコンテナ環境でエージェントバックエンドを運用する際の最大の障壁は、状態管理とセッション維持です。従来のModel Context Protocol (MCP) の構成は単一コネクションに依存するステートフルな接続が多く、マルチノードのクラウド環境でトラフィックを分散させるとセッションが消失したり、同期が壊れたりする致命的な制限がありました。@platformatic/mcp プラグインは、Fastifyフレームワーク上でこのアーキテクチャ的な限界を克服するために設計されました。

このプラグインは、Redisをメッセージブロードキャスティングおよびセッション状態共有のバックエンドとして活用します。ロードバランサー配下のバックエンドノードが動的に入れ替わったり水平スケーリングされたりしても、エージェントクライアントが確立しているサーバー送信イベント (SSE) コネクションのセッションを継続的に追跡・復旧できます。また、Fastifyエコシステムの高性能スキーマコンパイラであるTypeBoxをデフォルトの検証レイヤーとして統合しており、ランタイムのスキーマ検証性能を最大限に引き出します。

以下は、Redisをバックエンドとして統合し、分散インフラでの水平スケーリングをサポートするMCPサーバーの具体的な実装例です。

import Fastify from 'fastify';
import mcp from '@platformatic/mcp';
import { Type } from '@sinclair/typebox';

const app = Fastify();

await app.register(mcp, {
  redis: {
    host: 'localhost',
    port: 6379
  },
  enableSSE: true
});

app.mcpAddTool({
  name: 'get_user_activity',
  description: '사용자의 최근 활동 로그를 조회합니다.',
  inputSchema: Type.Object({
    userId: Type.String(),
    limit: Type.Optional(Type.Number({ default: 10 }))
  })
}, async (params) => {
  const { userId, limit } = params;
  return {
    content: [{ type: 'text', text: `사용자 ${userId}의 최근 활동 ${limit}건을 조회했습니다.` }]
  };
});

開発者は複雑な分散同期コードを自前で実装する必要はなく、宣言的なプラグイン設定を行うだけで、分散クラスター全体で動作するエージェントツールをデプロイできます。

@mcp-it/fastifyによる既存APIのAIツールへの自動変換

苦労して作成した既存のビジネスAPIをエージェント用ツールに変換するのは、バックエンド開発者にとって大きな負担です。@mcp-it/fastify プラグインは、Fastifyの強力なスキーマベースのルーティングアーキテクチャを活用することでこのボトルネックを解消します。ルートに宣言済みのJSONスキーマを動的に解析し、LLMが即座に理解・呼び出し可能なMCPツール仕様へと自動変換するからです。

余分なコードを記述することなく、既存のFastify APIをAIツールへ転換する方法は以下の通りです。

import Fastify from 'fastify';
import mcpPlugin from '@mcp-it/fastify';

const app = Fastify();

await app.register(mcpPlugin, {
  name: 'Core Business API',
  description: 'AI 에이전트 연동용 핵심 비즈니스 API',
});

app.get('/users/:id', {
  schema: {
    operationId: 'get_user_by_id',
    summary: '사용자 정보 조회',
    description: 'ID 기반으로 특정 사용자의 프로필 상세 정보를 반환합니다.',
    params: {
      type: 'object',
      required: ['id'],
      properties: {
        id: { type: 'number', description: '사용자의 고유 식별자' }
      }
    }
  }
}, async (request) => {
  const { id } = request.params as { id: number };
  return { id, name: '홍길동', email: 'user@example.com' };
});

@mcp-it/fastifyは、アプリケーションのルート登録フックをインターセプトして、すべてのパスを自動スキャンします。この過程でoperationIdがツールの固有名として指定され、既存のスキーマ構造がツールパラメーター定義と1対1で連携されます。開発者は同一のバリデーションロジックやビジネスロジックを二重管理する必要がなくなり、エージェント対応のコストを劇的に削減できます。

MastraとGenkitアダプターによるエージェントオーケストレーション

単に個別のツールを公開する段階を超え、複雑なマルチエージェントのワークフローやプロンプトパイプラインを構築する際には、MastraやGoogle Genkitのようなオーケストレーションフレームワークの専用アダプターが有用です。過去のようにエージェント専用サーバーを別途立ち上げて管理コストやシステム複雑性を増大させる必要はありません。現在運用中のFastifyプロセス内にエージェントエンジンを直接マウントすることで、一つのサーバーで高性能なビジネスロジックとエージェント機能を同時に運用できます。

公式 @mastra/fastify パッケージは、Mastraインスタンスに登録されたすべてのエージェント、ワークフロー、MCPサーバーエンドポイントをFastifyルーターに自動的にバインディングします。特にストリーム応答内の機密情報（システムプロンプト、ツール仕様、APIキーなど）をマスクするフィルタリングオプション（streamOptions）や、パスごとの認証ポリシー設定をコンストラクター段階で宣言的にサポートしており、セキュリティとプライバシー管理がより容易になります。

// Fastify 환경에 Mastra 에이전트 통합하기 (Mastra 1.0 기준)
import Fastify from 'fastify';
import { MastraServer } from '@mastra/fastify';
import { mastra } from './mastra'; // 초기화된 mastra 인스턴스

const app = Fastify({ logger: true });

// 어댑터를 통해 Mastra 에이전트 및 워크플로 엔드포인트를 Fastify에 마운트
const server = new MastraServer({ app, mastra });
await server.init();

await app.listen({ port: 3000 });

Googleが提供する @genkit-ai/fastify パッケージもまた、優れた開発体験をもたらします。このパッケージが提供する fastifyHandler は、複雑な入出力スキーマの検証とストリーミング処理を簡潔にまとめるミドルウェアの役割を果たします。クライアントがSSEストリーミングをリクエストする場合、別途ストリームパイピングのコードを書かなくてもリアルタイムのチャンク転送とCORSヘッダーのコピーを自動で行うため、フロントエンドとリアルタイム対話インターフェースを連携させる際に発生しがちな通信ボトルネックをスマートに解消します。

プラグインベースの未来志向なエージェントインフラ設計

エージェントインフラを設計する際、Fastifyの比類なきプラグインカプセル化アーキテクチャは、個別のツールやワークフローを安全に分離し、柔軟に結合するための最適な基盤を提供します。もはやルーティングやデータ変換を手動で実装する非効率から脱却し、標準化されたアダプターやミドルウェアを導入して、複雑な非同期処理を任せるべき時です。検証されたエコシステムツールを通じてステートレス環境のセキュリティ仕様を容易に満たしつつ、ビジネスの中核となるロジックとパフォーマンスの最適化に集中することが、次世代のAgenticバックエンドアーキテクチャの進むべき方向です。

参考リンク