30분 만에 구축하는 Claude 전용 커스텀 도구, MCP 서버 설계 가이드

Context

LLM이 외부 데이터나 실시간 정보에 접근하는 경로의 제한적 구조. 정적인 학습 데이터 외에 최신 API 데이터나 내부 시스템 연동을 위한 표준 인터페이스 필요성 대두.

Technical Solution

• @modelcontextprotocol/sdk 기반의 서버 프로세스를 구축하여 Claude Code와 독립적으로 실행되는 아키텍처 설계
• StdioServerTransport를 이용해 LLM 클라이언트와 서버 간 표준 입출력 방식의 통신 채널 형성
• Zod 라이브러리를 활용한 엄격한 Input Schema 정의로 도구 호출 파라미터의 타입 안정성 확보
• ListToolsRequestSchema와 CallToolRequestSchema 핸들러를 분리하여 도구 목록 제공과 실제 로직 실행을 구분하는 요청 처리 구조
• LLM의 추론 능력을 극대화하기 위해 포맷팅된 텍스트가 아닌 raw JSON 형태의 구조화된 데이터 반환 전략
• 상세한 도구 이름과 설명을 제공하여 LLM이 적절한 시점에 도구를 선택하도록 유도하는 프롬프트 엔지니어링 기반 설계

Key Takeaway

LLM 확장 도구 설계 시 인터페이스의 정밀한 정의와 구조화된 데이터 반환이 모델의 추론 정확도와 도구 선택률을 결정하는 핵심 요소임.