MCP Best Practices: 7 Hard Lessons I Learned Building 5 MCP Servers (Full Checklists Included)

개요

MCP(Model Context Protocol) 서버 구축 시 경험한 7가지 주요 문제점과 해결 방안을 제시하여 MCP 서버 개발의 실무적 지침을 제공합니다.

주요 내용

* 빈 응답 처리: 결과가 없을 경우 빈 배열 대신, 결과가 없음을 알리는 사람이 읽을 수 있는 메시지를 반환하여 클라이언트의 무한 대기를 방지해야 합니다.
* JSON 직렬화: JSON 문자열을 직접 수동으로 생성하는 대신, 프레임워크의 직렬화 기능을 사용하여 데이터의 특수 문자로 인한 파싱 오류를 방지해야 합니다.
* API 키 인증: Authorization: Bearer 헤더 외에도 X-API-Key 헤더, api_key 또는 apiKey 쿼리 파라미터 등 다양한 위치에서 API 키를 지원하여 클라이언트 호환성을 높여야 합니다.
* CORS 사전 요청 (Preflight): 웹 기반 클라이언트의 경우 OPTIONS 사전 요청 시 인증이 필요 없도록 CORS 설정을 조정하고, 인증 필터에서 OPTIONS 메서드를 건너뛰도록 처리해야 합니다.
* 느린 응답 처리: 콜드 스타트 등으로 인해 응답이 늦어지는 경우, HTTP 상태 및 헤더를 조기에 플러시하여 연결을 유지하고 타임아웃을 방지해야 합니다.
* Content-Length 명시: 청크 인코딩 문제를 피하고 응답 잘림을 방지하기 위해 가능한 경우 Content-Length 헤더를 명시적으로 설정해야 합니다.
* 헬스 체크 엔드포인트: /health와 같은 간단한 헬스 체크 엔드포인트를 제공하여 서비스 모니터링 및 자동 재시작을 가능하게 해야 합니다.

시사점

MCP는 표준 프로토콜, 데이터 프라이버시, 단순한 아키텍처 등의 장점을 가지지만, 클라이언트 간 파편화, 문서 부족, 생태계 채택 등의 개선이 필요한 초기 단계의 기술입니다.