Fastify 에이전틱 미들웨어 — 수동 구현 없는 MCP v2.0 백엔드 패턴

모델 컨텍스트 프로토콜(MCP) v2.0 규격이 무상태 HTTP 표준을 채택하면서, AI 에이전트와 백엔드 API를 연결하는 방식이 전환되고 있습니다. 기존에는 LLM이 호출할 도구를 개발자가 매번 가공하고 복잡한 라우팅 규칙을 일일이 수작업으로 관리해야 했습니다. 하지만 현재 Fastify 생태계는 공식 어댑터와 고성능 플러그인을 활용해 상태 비저장 분산 처리와 보안 검증을 자동으로 수행하는 에이전틱 미들웨어 패턴으로 빠르게 발전하고 있습니다.

공식 @modelcontextprotocol/fastify 어댑터 도입하기

공식 @modelcontextprotocol/fastify 패키지는 Fastify 애플리케이션 위에서 MCP 규격을 준수하는 도구를 호스팅하기 위한 최적의 전용 어댑터입니다. 이 어댑터는 무상태 환경에서 필수적인 DNS 리바인딩 보호와 호스트 헤더 검증을 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)를 기본 검증 레이어로 결합하여 런타임 스키마 검증 성능을 극대화합니다.

다음은 레디스를 백엔드로 결합하여 분산 인프라에서 수평 확장을 지원하는 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)와 구글 젠키트(Genkit) 같은 오케스트레이션 프레임워크의 전용 어댑터가 유용합니다. 과거처럼 별도의 에이전트 독립 서버를 띄워 관리 비용과 시스템 복잡도를 늘릴 필요 없이, 기존에 운영 중인 Fastify 프로세스 내에 에이전트 엔진을 직접 마운트하여 하나의 단일 서버로 고성능 비즈니스 로직과 에이전트 기능을 한 번에 운영할 수 있습니다.

공식 @mastra/fastify 패키지는 마스트라 인스턴스에 등록된 모든 에이전트, 워크플로, 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 });

구글이 배포한 @genkit-ai/fastify 패키지 역시 뛰어난 개발자 경험을 선사합니다. 이 패키지가 제공하는 fastifyHandler는 복잡한 입출력 스키마 검증과 스트리밍 처리를 간결하게 묶어주는 미들웨어 역할을 합니다. 클라이언트가 SSE 스트리밍을 요청할 경우 별도의 스트림 파이핑 코드 없이도 실시간 청크 전송과 CORS 헤더 복사를 자동으로 수행하므로, 프론트엔드와 실시간 대화 인터페이스를 맞물릴 때 발생하기 쉬운 통신 병목을 우아하게 해소합니다.

플러그인 기반의 미래 지향적 에이전트 인프라 설계

에이전트 인프라를 설계할 때 Fastify의 독보적인 플러그인 캡슐화 아키텍처는 개별 도구와 워크플로를 안전하게 격리하고 유연하게 결합하는 최적의 기반을 제공합니다. 이제는 라우팅이나 데이터 변환을 수동으로 구현하는 비효율에서 벗어나, 표준화된 어댑터와 미들웨어를 도입해 복잡한 비동기 흐름을 위임해야 할 때입니다. 검증된 생태계 도구를 통해 무상태 환경의 보안 규격을 손쉽게 충족하면서, 비즈니스 핵심 로직과 성능 최적화에 집중하는 것이 다음 단계의 에이전틱 백엔드 아키텍처가 나아가야 할 방향입니다.

참고 링크