실전 MCP 통합 프로젝트 완벽 가이드

Model Context Protocol을 활용한 실전 통합 프로젝트를 처음부터 끝까지 구축하는 방법을 다룹니다. 아키텍처 설계부터 멀티 서버 통합, 모니터링, 배포까지 운영 레벨의 MCP 시스템을 구축하는 노하우를 담았습니다.

---

목차

1. 프로젝트_아키텍처_설계
2. 멀티_서버_통합
3. 클라이언트_구현
4. 모니터링_및_로깅
5. 배포_전략
6. 운영_베스트_프랙티스

---

1. 프로젝트 아키텍처 설계

스타트업에서 일하는 김개발 씨는 팀장님으로부터 뜻밖의 미션을 받았습니다. "우리도 AI 에이전트를 도입해야 해.

MCP로 여러 서비스를 통합해서 자동화 시스템을 구축해줘." 막막함과 설렘이 교차하는 순간, 김개발 씨는 가장 먼저 아키텍처 설계부터 시작하기로 했습니다.

MCP 아키텍처란 AI 에이전트가 여러 도구와 서비스를 일관된 방식으로 활용할 수 있도록 설계하는 시스템 구조입니다. 마치 교향악단의 지휘자가 각 파트를 조율하듯, MCP 아키텍처는 다양한 서버와 클라이언트가 조화롭게 동작하도록 전체 구조를 설계합니다.

이를 통해 확장성과 유지보수성을 모두 갖춘 AI 통합 시스템을 구축할 수 있습니다.

다음 코드를 살펴봅시다.

// mcp-architecture/project-structure.ts
// MCP 프로젝트의 기본 아키텍처 구조
interface MCPArchitecture {
  // 서버 레이어: 도구와 리소스 제공
  servers: {
    database: MCPServer;      // 데이터베이스 접근
    fileSystem: MCPServer;    // 파일 시스템 조작
    externalAPI: MCPServer;   // 외부 API 연동
  };
  // 클라이언트 레이어: AI 에이전트 연결
  client: {
    transport: 'stdio' | 'sse' | 'websocket';
    connectionPool: number;   // 연결 풀 크기
  };
  // 게이트웨이: 라우팅과 인증 처리
  gateway: {
    loadBalancer: boolean;
    authentication: 'jwt' | 'apiKey';
  };
}

김개발 씨는 화이트보드 앞에 섰습니다. 좋은 건물을 짓기 전에 설계도가 필요하듯, 좋은 시스템을 만들기 전에 아키텍처가 필요합니다.

그렇다면 MCP 통합 프로젝트의 아키텍처는 어떻게 설계해야 할까요? MCP 아키텍처를 이해하는 가장 좋은 방법은 공항에 비유하는 것입니다.

공항에는 각 항공사 카운터(서버), 여행객(클라이언트), 그리고 이 모든 것을 관리하는 공항 관제탑(게이트웨이)이 있습니다. 각자 역할이 다르지만, 전체가 유기적으로 연결되어 있습니다.

먼저 서버 레이어를 살펴봅시다. 이 계층에서는 실제 도구와 리소스를 제공합니다.

데이터베이스 서버는 SQL 쿼리를 실행하고, 파일 시스템 서버는 문서를 읽고 쓰며, 외부 API 서버는 슬랙이나 지라 같은 서비스와 통신합니다. 각 서버는 독립적으로 동작하므로 하나가 문제가 생겨도 다른 서버에 영향을 주지 않습니다.

다음으로 클라이언트 레이어입니다. AI 에이전트가 실제로 서버와 통신하는 계층입니다.

어떤 프로토콜로 통신할지, 동시에 몇 개의 연결을 유지할지 결정합니다. stdio는 로컬 환경에, SSE나 WebSocket은 원격 환경에 적합합니다.

마지막으로 게이트웨이 레이어가 있습니다. 모든 요청이 이 관문을 통과합니다.

인증을 확인하고, 적절한 서버로 요청을 라우팅하며, 로드 밸런싱까지 담당합니다. 실제 운영 환경에서 보안과 안정성을 책임지는 핵심 계층입니다.

위 코드를 보면 MCPArchitecture 인터페이스가 세 가지 주요 영역을 정의하고 있습니다. servers 객체는 세 가지 MCP 서버를 선언하고, client는 통신 방식과 연결 풀을 설정합니다.

gateway는 로드 밸런싱과 인증 방식을 결정합니다. 박시니어 씨가 김개발 씨의 설계를 보더니 고개를 끄덕였습니다.

"좋아요. 계층 분리가 잘 되어 있네요.

하지만 한 가지 빠진 게 있어요." 그것은 바로 장애 격리였습니다. 각 서버 간에 의존성을 최소화해야 한 서버의 장애가 전체 시스템을 멈추지 않습니다.

실무에서는 이런 아키텍처를 마이크로서비스 패턴과 함께 적용합니다. 각 MCP 서버를 독립적인 컨테이너로 배포하면 확장과 롤백이 용이해집니다.

쿠버네티스나 도커 스웜 같은 오케스트레이션 도구와 궁합이 잘 맞습니다. 주의할 점도 있습니다.

너무 많은 서버로 분리하면 오히려 복잡성이 증가합니다. 처음에는 3~5개 정도의 핵심 서버로 시작하고, 필요에 따라 점진적으로 확장하는 것이 좋습니다.

과도한 설계는 오히려 독이 됩니다. 김개발 씨는 화이트보드에 그린 아키텍처 다이어그램을 사진으로 찍어두었습니다.

이제 기초 설계가 완료되었으니, 실제 구현을 시작할 차례입니다.

실전 팁

💡 - 아키텍처 설계 시 **ADR(Architecture Decision Record)**을 작성하여 결정 이유를 문서화하세요

• 처음부터 완벽한 설계를 추구하지 말고, 점진적 개선을 목표로 하세요
• 각 계층 간 인터페이스를 명확히 정의하면 나중에 구현을 교체하기 쉽습니다

---

2. 멀티 서버 통합

아키텍처 설계를 마친 김개발 씨는 이제 실제 서버들을 연결하는 작업에 착수했습니다. 데이터베이스, 파일 시스템, 외부 API까지 세 개의 MCP 서버를 하나의 클라이언트에서 관리해야 합니다.

"어떻게 하면 여러 서버를 깔끔하게 통합할 수 있을까?" 고민이 시작되었습니다.

멀티 서버 통합은 여러 MCP 서버를 단일 진입점에서 관리하고 조율하는 기술입니다. 마치 리모컨 하나로 TV, 에어컨, 조명을 모두 제어하는 스마트홈 허브와 같습니다.

각 서버의 연결 상태를 관리하고, 요청을 적절한 서버로 라우팅하며, 전체 시스템의 일관성을 유지합니다.

다음 코드를 살펴봅시다.

// multi-server/server-aggregator.ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

class MultiServerManager {
  private servers: Map<string, Client> = new Map();

  // 서버 등록 및 연결
  async registerServer(name: string, command: string, args: string[]) {
    const transport = new StdioClientTransport({ command, args });
    const client = new Client({ name: `${name}-client`, version: '1.0.0' });
    await client.connect(transport);
    this.servers.set(name, client);
    console.log(`[${name}] 서버 연결 완료`);
  }

  // 특정 서버에서 도구 호출
  async callTool(serverName: string, toolName: string, args: object) {
    const client = this.servers.get(serverName);
    if (!client) throw new Error(`서버를 찾을 수 없습니다: ${serverName}`);
    return await client.callTool({ name: toolName, arguments: args });
  }
}

여러 MCP 서버를 통합한다는 것은 어떤 의미일까요? 김개발 씨는 처음에 각 서버마다 별도의 연결 코드를 작성했습니다.

하지만 서버가 늘어날수록 코드가 복잡해지고, 관리가 어려워졌습니다. 이 문제를 해결하는 핵심은 중앙 집중식 관리입니다.

마치 호텔의 프론트 데스크가 모든 객실을 관리하듯, 하나의 매니저 클래스가 모든 서버 연결을 관리합니다. 손님이 어떤 서비스를 요청하든 프론트를 통하면 됩니다.

위 코드에서 MultiServerManager 클래스가 이 역할을 담당합니다. servers라는 Map에 서버 이름을 키로, Client 인스턴스를 값으로 저장합니다.

새 서버를 추가하려면 registerServer 메서드만 호출하면 됩니다. registerServer 메서드를 자세히 살펴봅시다.

먼저 StdioClientTransport를 생성하여 통신 채널을 만듭니다. 그 다음 Client 인스턴스를 생성하고 connect 메서드로 실제 연결을 수립합니다.

마지막으로 Map에 등록하여 나중에 이름으로 찾을 수 있게 합니다. callTool 메서드는 실제 도구를 호출하는 통합 인터페이스입니다.

서버 이름과 도구 이름, 인자를 받아서 해당 서버에 요청을 전달합니다. 만약 존재하지 않는 서버를 호출하면 명확한 에러 메시지를 반환합니다.

박시니어 씨가 코드를 리뷰하면서 한 가지 제안을 했습니다. "연결이 끊어졌을 때 자동으로 재연결하는 로직도 추가하면 좋겠어요." 실제 운영 환경에서는 네트워크 불안정으로 연결이 끊어질 수 있기 때문입니다.

실무에서는 헬스체크도 필수입니다. 주기적으로 각 서버의 상태를 확인하고, 문제가 있으면 알림을 보내거나 자동 복구를 시도합니다.

이를 위해 별도의 모니터링 스레드나 타이머를 사용합니다. 여러 서버를 통합할 때 주의할 점은 순환 의존성입니다.

서버 A가 서버 B를 호출하고, 서버 B가 다시 서버 A를 호출하면 무한 루프에 빠질 수 있습니다. 호출 체인을 명확히 설계하고, 필요하다면 호출 깊이 제한을 두어야 합니다.

김개발 씨는 이제 데이터베이스, 파일 시스템, 슬랙 서버를 모두 하나의 매니저로 관리할 수 있게 되었습니다. AI 에이전트가 어떤 작업을 요청하든, 적절한 서버로 라우팅되어 처리됩니다.

실전 팁

💡 - 서버 연결 시 타임아웃을 설정하여 무한 대기를 방지하세요

• 연결 풀을 사용하면 서버 부하가 분산되고 응답 시간이 개선됩니다
• 서버 목록은 설정 파일로 분리하여 코드 수정 없이 서버를 추가할 수 있게 하세요

---

3. 클라이언트 구현

서버 통합을 마친 김개발 씨는 이제 실제로 AI와 상호작용할 클라이언트를 구현해야 했습니다. "서버만 잘 돌아간다고 끝이 아니네.

사용자와 AI가 편하게 쓸 수 있는 인터페이스가 필요해." 클라이언트 개발이라는 새로운 도전이 시작되었습니다.

MCP 클라이언트는 AI 에이전트와 MCP 서버 사이를 연결하는 다리 역할을 합니다. 마치 동시통역사가 두 언어 사이에서 의사소통을 돕듯, 클라이언트는 AI의 요청을 MCP 프로토콜로 변환하고, 서버의 응답을 AI가 이해할 수 있는 형태로 전달합니다.

다음 코드를 살펴봅시다.

// client/mcp-client.ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

class MCPClient {
  private client: Client;
  private tools: Map<string, any> = new Map();

  async initialize(serverUrl: string) {
    // SSE 트랜스포트로 원격 서버 연결
    const transport = new SSEClientTransport(new URL(serverUrl));
    this.client = new Client({ name: 'ai-agent-client', version: '1.0.0' });
    await this.client.connect(transport);
    // 사용 가능한 도구 목록 캐싱
    const { tools } = await this.client.listTools();
    tools.forEach(tool => this.tools.set(tool.name, tool));
    console.log(`${tools.length}개의 도구를 로드했습니다`);
  }

  // AI 에이전트용 도구 실행 래퍼
  async executeTool(name: string, args: object): Promise<string> {
    const result = await this.client.callTool({ name, arguments: args });
    return JSON.stringify(result.content, null, 2);
  }
}

클라이언트 구현은 왜 중요할까요? 아무리 좋은 서버가 있어도 접근하기 어려우면 무용지물입니다.

김개발 씨는 AI 에이전트가 마치 사람처럼 자연스럽게 도구를 사용할 수 있도록 클라이언트를 설계하기로 했습니다. 위 코드에서 MCPClient 클래스는 크게 두 가지 책임을 가집니다.

첫째는 서버 연결 관리, 둘째는 도구 호출 간소화입니다. 복잡한 MCP 프로토콜을 감추고, 단순한 메서드 호출만으로 모든 기능을 사용할 수 있게 합니다.

initialize 메서드에서는 SSEClientTransport를 사용합니다. SSE(Server-Sent Events)는 HTTP 기반의 스트리밍 프로토콜로, 방화벽 통과가 쉽고 웹 환경과 호환성이 좋습니다.

원격 서버에 연결할 때 자주 사용하는 방식입니다. 연결이 완료되면 listTools를 호출하여 사용 가능한 도구 목록을 가져옵니다.

이 목록을 Map에 캐싱해두면 나중에 도구가 존재하는지 빠르게 확인할 수 있습니다. 매번 서버에 질의하지 않아도 되므로 성능이 향상됩니다.

executeTool 메서드는 AI 에이전트를 위한 간편 래퍼입니다. 도구 이름과 인자만 전달하면 내부적으로 callTool을 호출하고, 결과를 JSON 문자열로 변환하여 반환합니다.

AI 모델이 파싱하기 쉬운 형태로 응답을 정리해주는 것입니다. 박시니어 씨가 한 가지 팁을 알려주었습니다.

"도구 실행 결과를 로깅해두면 나중에 디버깅할 때 정말 유용해요." 어떤 도구가 어떤 인자로 호출되었고, 결과가 무엇이었는지 추적할 수 있기 때문입니다. 실무에서는 재시도 로직도 중요합니다.

네트워크 일시적 오류나 서버 과부하로 요청이 실패할 수 있습니다. 지수 백오프(exponential backoff) 전략으로 재시도하면 일시적인 문제를 자동으로 극복할 수 있습니다.

클라이언트를 구현할 때 흔히 하는 실수는 에러 처리 누락입니다. 서버가 응답하지 않거나, 잘못된 도구 이름을 호출하거나, 인자 형식이 틀렸을 때 적절한 에러 메시지를 반환해야 합니다.

그래야 AI 에이전트가 다른 방법을 시도하거나 사용자에게 알릴 수 있습니다. 김개발 씨의 클라이언트가 완성되었습니다.

이제 AI 에이전트는 단 몇 줄의 코드로 데이터베이스를 쿼리하고, 파일을 읽고, 슬랙에 메시지를 보낼 수 있습니다.

실전 팁

💡 - 클라이언트 초기화는 애플리케이션 시작 시 한 번만 수행하고 인스턴스를 재사용하세요

• 도구 실행 결과는 적절한 크기로 잘라서 반환하세요. AI 모델의 컨텍스트 한계가 있습니다
• TypeScript의 제네릭을 활용하면 도구별 타입 안전성을 확보할 수 있습니다

---

4. 모니터링 및 로깅

시스템이 잘 돌아가는 것 같았습니다. 하지만 어느 날 아침, 팀장님이 급하게 김개발 씨를 불렀습니다.

"어젯밤에 시스템이 느려졌다는 불만이 있었어. 무슨 일이 있었던 거야?" 로그를 확인하려 했지만, 제대로 된 기록이 없어 원인을 파악할 수 없었습니다.

모니터링과 로깅은 시스템의 눈과 귀입니다. 마치 자동차의 계기판이 연료량, 속도, 엔진 상태를 보여주듯, 모니터링은 시스템의 현재 상태를 실시간으로 보여줍니다.

로깅은 블랙박스처럼 과거에 무슨 일이 있었는지 기록하여 문제 발생 시 원인을 추적할 수 있게 해줍니다.

다음 코드를 살펴봅시다.

// monitoring/logger.ts
import winston from 'winston';

// 구조화된 로깅 설정
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'logs/error.log', level: 'error' }),
    new winston.transports.File({ filename: 'logs/combined.log' }),
  ],
});

// MCP 요청 로깅 미들웨어
function logMCPRequest(serverName: string, toolName: string, args: object) {
  const startTime = Date.now();
  return (result: any, error?: Error) => {
    const duration = Date.now() - startTime;
    logger.info('MCP 도구 호출', {
      server: serverName, tool: toolName, args,
      duration, success: !error, error: error?.message
    });
  };
}

그날 이후 김개발 씨는 모니터링의 중요성을 뼈저리게 느꼈습니다. 문제가 발생한 후에야 로그가 없다는 것을 깨달은 것입니다.

박시니어 씨가 말했습니다. "프로덕션에서는 **관찰 가능성(Observability)**이 생명이야." 모니터링과 로깅을 이해하려면 병원을 떠올리면 됩니다.

환자의 심박수, 혈압, 체온을 실시간으로 모니터링하면 위험 신호를 즉시 감지할 수 있습니다. 로그는 환자의 진료 기록과 같아서, 과거 이력을 통해 현재 증상의 원인을 파악합니다.

위 코드에서는 Winston 라이브러리를 사용합니다. Node.js 생태계에서 가장 널리 사용되는 로깅 라이브러리입니다.

JSON 형식으로 로그를 기록하면 나중에 검색하고 분석하기 쉽습니다. 로거 설정에서 두 가지 transport를 정의했습니다.

에러 로그는 별도 파일에, 모든 로그는 combined.log에 기록됩니다. 에러만 빠르게 확인해야 할 때 error.log만 보면 되므로 효율적입니다.

logMCPRequest 함수는 클로저를 활용한 패턴입니다. 요청 시작 시점에 startTime을 기록하고, 완료 시점에 duration을 계산합니다.

이렇게 하면 각 도구 호출이 얼마나 걸렸는지 정확히 알 수 있습니다. 실무에서는 로그만으로는 부족합니다.

메트릭도 함께 수집해야 합니다. 초당 요청 수, 평균 응답 시간, 에러율 같은 숫자 데이터를 Prometheus 같은 도구로 수집하고 Grafana로 시각화합니다.

이상 징후가 발생하면 슬랙으로 알림을 보내도록 설정할 수 있습니다. 분산 환경에서는 **추적(Tracing)**도 필수입니다.

하나의 요청이 여러 서버를 거칠 때, 각 구간의 소요 시간을 추적합니다. OpenTelemetry 같은 표준을 사용하면 다양한 모니터링 도구와 연동할 수 있습니다.

흔한 실수 중 하나는 민감 정보 로깅입니다. 사용자 비밀번호나 API 키가 로그에 남으면 보안 사고로 이어집니다.

로깅 전에 민감 정보를 마스킹하는 필터를 반드시 적용해야 합니다. 김개발 씨는 모니터링 대시보드를 구축한 후, 시스템 상태를 한눈에 파악할 수 있게 되었습니다.

이제 문제가 발생해도 빠르게 원인을 찾고 대응할 수 있습니다.

실전 팁

💡 - 로그 레벨(debug, info, warn, error)을 적절히 사용하여 노이즈를 줄이세요

• 로그 로테이션을 설정하여 디스크 공간이 가득 차는 것을 방지하세요
• 개발 환경에서는 콘솔 출력을, 프로덕션에서는 파일이나 외부 서비스로 로그를 전송하세요

---

5. 배포 전략

개발이 완료된 MCP 시스템을 드디어 프로덕션에 배포할 시간이 되었습니다. 김개발 씨는 긴장되었습니다.

"개발 환경에서는 잘 돌아갔는데, 실제 서비스에서도 문제없이 동작할까?" 안전하고 효율적인 배포 전략이 필요한 순간입니다.

배포 전략은 개발 환경에서 만든 코드를 실제 서비스에 안전하게 적용하는 방법론입니다. 마치 비행기가 이륙하기 전 체크리스트를 확인하듯, 배포 전략은 코드가 프로덕션에 도달하기까지의 모든 과정을 체계화합니다.

문제가 생기면 빠르게 롤백할 수 있는 안전망도 포함됩니다.

다음 코드를 살펴봅시다.

// deploy/docker-compose.yml 형태의 TypeScript 설정
interface DeploymentConfig {
  // 블루-그린 배포 설정
  blueGreen: {
    activeSlot: 'blue' | 'green';
    healthCheckPath: string;
    switchTimeout: number;  // ms
  };
  // 컨테이너 설정
  containers: {
    mcpServer: {
      image: string;
      replicas: number;
      resources: { cpu: string; memory: string };
    };
    gateway: {
      image: string;
      ports: string[];
    };
  };
  // 롤백 정책
  rollback: {
    automaticOnFailure: boolean;
    keepPreviousVersions: number;
  };
}

// 배포 스크립트 예시
async function deploy(config: DeploymentConfig) {
  const targetSlot = config.blueGreen.activeSlot === 'blue' ? 'green' : 'blue';
  console.log(`새 버전을 ${targetSlot} 슬롯에 배포합니다`);
  // 1. 새 버전 배포 -> 2. 헬스체크 -> 3. 트래픽 전환
}

배포는 왜 이렇게 신경 써야 할까요? 박시니어 씨가 경험담을 들려주었습니다.

"예전에 금요일 저녁에 배포했다가 주말 내내 불이 꺼지지 않았어요." 배포 실패는 서비스 장애로 이어지고, 이는 곧 비즈니스 손실입니다. 배포 전략을 이해하려면 교대 근무를 생각하면 됩니다.

현재 근무자가 일하는 동안 다음 근무자가 대기합니다. 인수인계가 완료되면 교대합니다.

문제가 생기면 이전 근무자가 다시 투입됩니다. 블루-그린 배포가 바로 이런 방식입니다.

위 코드의 DeploymentConfig를 살펴봅시다. blueGreen 설정에서 현재 활성 슬롯과 헬스체크 경로, 전환 타임아웃을 정의합니다.

새 버전은 비활성 슬롯에 배포되고, 헬스체크를 통과하면 트래픽이 전환됩니다. containers 설정에서는 각 서비스의 도커 이미지와 리소스를 정의합니다.

replicas를 2 이상으로 설정하면 하나의 인스턴스가 죽어도 다른 인스턴스가 요청을 처리합니다. 고가용성의 기본입니다.

rollback 설정이 핵심입니다. automaticOnFailure를 true로 설정하면 배포 후 헬스체크가 실패할 때 자동으로 이전 버전으로 돌아갑니다.

keepPreviousVersions는 몇 개의 이전 버전을 보관할지 결정합니다. 긴급 롤백이 필요할 때 유용합니다.

실무에서는 카나리 배포도 많이 사용합니다. 전체 트래픽의 5%만 새 버전으로 보내고, 문제가 없으면 점진적으로 비율을 높입니다.

리스크를 최소화하면서 새 기능을 검증할 수 있습니다. 배포 시 주의할 점은 데이터베이스 마이그레이션입니다.

스키마 변경이 있으면 이전 버전과 새 버전이 동시에 동작할 수 있도록 호환성을 유지해야 합니다. 먼저 스키마를 확장하고, 코드를 배포하고, 마지막에 불필요한 컬럼을 제거하는 순서를 따릅니다.

김개발 씨는 CI/CD 파이프라인을 구축하여 코드가 푸시되면 자동으로 테스트, 빌드, 배포가 진행되도록 했습니다. 이제 배포가 두렵지 않습니다.

실전 팁

💡 - 금요일 오후 배포 금지 - 문제 발생 시 주말에 대응해야 합니다

• 배포 전 스테이징 환경에서 충분히 테스트하세요
• 롤백 절차를 정기적으로 훈련하여 실제 상황에서 빠르게 대응할 수 있게 하세요

---

6. 운영 베스트 프랙티스

시스템이 안정적으로 운영되고 있습니다. 하지만 김개발 씨는 알고 있었습니다.

진짜 도전은 이제부터라는 것을. 장기적으로 시스템을 건강하게 유지하려면 어떻게 해야 할까요?

박시니어 씨가 수년간 쌓은 운영 노하우를 전수해주기로 했습니다.

운영 베스트 프랙티스는 시스템을 장기간 안정적으로 유지하기 위한 검증된 방법론들의 집합입니다. 마치 자동차를 오래 타려면 정기 점검과 오일 교환이 필요하듯, 소프트웨어 시스템도 지속적인 관리와 개선이 필요합니다.

좋은 운영 습관은 장애를 예방하고, 발생해도 빠르게 복구할 수 있게 해줍니다.

다음 코드를 살펴봅시다.

// operations/best-practices.ts
interface OperationalPolicy {
  // 정기 점검 일정
  maintenance: {
    healthCheckInterval: number;      // 5분마다 헬스체크
    logRotationDays: number;          // 30일 후 로그 삭제
    dependencyUpdateWeekly: boolean;  // 주간 의존성 업데이트
  };
  // 장애 대응 정책
  incidentResponse: {
    alertThresholds: {
      errorRate: number;    // 5% 초과 시 알림
      latencyP99: number;   // 99퍼센타일 2초 초과 시
    };
    oncallRotation: string[];  // 당직 순환 멤버
    escalationPath: string[];  // 에스컬레이션 경로
  };
  // 용량 계획
  capacityPlanning: {
    cpuScaleUpThreshold: number;   // CPU 70% 시 스케일업
    memoryWarningThreshold: number; // 메모리 80% 경고
    storageAlertThreshold: number;  // 스토리지 90% 알림
  };
}

"시스템은 배포하고 나면 끝이 아니에요." 박시니어 씨가 말했습니다. "오히려 그때부터 시작이죠." 운영은 마라톤과 같습니다.

단기 성과보다 장기적인 지속 가능성이 중요합니다. 위 코드의 OperationalPolicy는 세 가지 핵심 영역을 다룹니다.

첫째 정기 점검, 둘째 장애 대응, 셋째 용량 계획입니다. 이 세 가지만 잘 관리해도 대부분의 운영 이슈를 예방하거나 빠르게 해결할 수 있습니다.

maintenance 설정은 예방 차원의 활동들입니다. 5분마다 헬스체크를 수행하여 문제를 조기에 발견합니다.

30일이 지난 로그는 삭제하여 디스크 공간을 확보합니다. 매주 의존성을 업데이트하여 보안 취약점에 대응합니다.

incidentResponse는 문제 발생 시 대응 체계입니다. 에러율이 5%를 넘거나 응답 시간이 느려지면 알림이 발송됩니다.

누가 당직인지, 해결이 안 되면 누구에게 에스컬레이션할지 미리 정해둡니다. 새벽 3시에 장애가 발생해도 혼란 없이 대응할 수 있습니다.

capacityPlanning은 미래를 대비하는 활동입니다. CPU 사용률이 70%에 도달하면 미리 인스턴스를 늘립니다.

80%가 되어서야 허둥대면 이미 사용자들이 느린 응답을 경험하고 있을 겁니다. 선제적 대응이 핵심입니다.

실무에서 박시니어 씨가 강조한 것은 문서화입니다. 런북(Runbook)이라고 불리는 운영 매뉴얼에 자주 발생하는 문제와 해결 방법을 기록해둡니다.

새로운 팀원이 합류해도, 당직자가 처음 보는 문제를 마주해도 대응할 수 있습니다. 정기 회고도 중요합니다.

매주 또는 매월 운영 상황을 되돌아보고, 개선점을 찾습니다. 같은 장애가 반복되면 근본 원인을 분석하여 재발을 방지합니다.

이런 과정이 쌓이면 시스템은 점점 더 안정적으로 변합니다. 주의할 점은 과도한 알림입니다.

중요하지 않은 알림이 너무 많으면 정작 중요한 알림을 놓칩니다. 알림 피로(alert fatigue)라고 불리는 현상입니다.

정말 대응이 필요한 것만 알림으로 설정하고, 나머지는 대시보드에서 확인하도록 합니다. 김개발 씨는 운영 정책 문서를 작성하고 팀과 공유했습니다.

이제 누가 당직이든, 어떤 문제가 발생하든 일관된 방식으로 대응할 수 있습니다. MCP 통합 프로젝트가 비로소 완성되었습니다.

실전 팁

💡 - 포스트모템 문화를 정착시키세요. 비난 없이 원인을 분석하고 개선점을 찾습니다

• 운영 지표를 가시화하여 팀 전체가 시스템 상태를 인지하게 하세요
• 카오스 엔지니어링을 도입하여 의도적으로 장애를 유발하고 대응력을 검증하세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!