Dev Hub1 month ago

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 옵션을 설정하는 것만으로 내부 동작 프로세스를 완전히 바꿉니다. 기존의 인메모리 세션 저장소는 다중 노드가 공유하는 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 헤더를 통해 레디스에 보관된 이전 이력에서 연결 스트림을 매끄럽게 재개합니다. 특히 비동기식 백그라운드 작업을 특정 노드에서 처리하는 중이더라도 클라이언트가 다른 분산 노드로 진행 상황을 폴링하여 안전하게 결과를 조회할 수 있어, 진정한 의미의 엔터프라이즈급 고가용성 에이전트 레이어를 완성할 수 있습니다.

프로덕션 도입을 위한 아키텍처 체크리스트

Fastify와 최신 모델 컨텍스트 프로토콜 생태계를 결합하여 고가용성 에이전트 백엔드를 구축할 때는 세 가지 핵심 설계 요소를 점검해야 합니다. 우선 공식 SDK v2.0에서 제공하는 호스트 헤더 검증 기능을 활성화하여 DNS 리바인딩 같은 보안 위협으로부터 에이전트 실행 환경을 보호해야 합니다. 또한, 동시 접속 요청이 몰리는 실무 환경에서는 도구 실행 속도가 전체 백엔드의 병목으로 이어지지 않도록 반드시 실행 시간 제한을 명확히 설정하십시오. 마지막으로 인스턴스 수평 확장 시 세션이 유실되지 않도록 레디스 기반의 세션 저장소와 분산 메시징 아키텍처를 도입하여 클라우드 환경에 최적화된 고성능 에이전트 인프라를 완성할 수 있습니다.

참고 링크

Comment

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