클로드(Claude)용 MCP(Model Context Protocol) 서버 구축 가이드

Building an MCP Server for Claude Code

작성자
Vitalii Elenhaupt
발행일
2025년 10월 03일
원문 보기
veelenga.github.io

핵심 요약

  • 1 MCP는 Claude의 기능을 외부 도구와 연동하여 확장하는 개방형 프로토콜로, 표준 입출력(stdio)을 통해 JSON-RPC 메시지를 교환합니다.
  • 2 MCP 서버는 도구 정의(이름, 상세 설명, JSON 스키마 기반 입력), 요청 처리(도구 목록, 도구 호출), 안전한 인자 처리 및 표준화된 응답 형식을 따릅니다.
  • 3 claude-mermaid 예시를 통해 서버 초기화, 도구 구현, 인자 유효성 검사, 파일 기반 로깅을 포함한 디버깅 및 배포 과정을 실질적으로 학습할 수 있습니다.

도입

Model Context Protocol(MCP)은 Claude와 같은 AI 어시스턴트가 외부 커스텀 도구와 상호작용할 수 있도록 지원하는 개방형 프로토콜입니다. 이는 Claude가 다이어그램 렌더링, 데이터베이스 쿼리, API 호출 등 다양한 외부 기능을 활용할 수 있는 범용 어댑터 역할을 합니다. 본 가이드는 claude-mermaid 예시를 통해 Mermaid 다이어그램을 라이브 브라우저 미리보기와 함께 렌더링하는 MCP 서버를 구축하는 과정을 상세히 설명합니다.

MCP 프로토콜 이해

MCP는 AI 어시스턴트와 외부 도구 간의 표준화된 인터페이스를 제공합니다. Claude는 도구를 검색하고, 필요에 따라 특정 인자와 함께 도구를 호출하며, 구조화된 응답을 받아 추론에 활용합니다. 통신은 stdio(표준 입출력)를 통해 JSON-RPC 메시지로 이루어지며, 이는 프로토콜의 단순성과 언어 독립성을 보장합니다.

서버 설정

모든 MCP 서버는 기본 초기화로 시작합니다. @modelcontextprotocol/sdk/server/index.js의 Server와 StdioServerTransport를 사용하여 서버를 설정하고, 서버의 기능(예: 도구 지원)을 선언합니다. 연결 후 서버는 Claude의 요청을 대기합니다.

도구 정의

도구는 MCP의 핵심이며, Claude에게 서버가 제공하는 기능과 사용 방법을 알려주는 계약서 역할을 합니다. 각 도구 정의는 다음 세 가지 필수 요소를 포함합니다.

  • 고유 식별자: name 필드로 도구를 호출하는 데 사용됩니다.

  • 상세 설명: description 필드는 Claude가 도구를 언제, 어떻게 사용할지 이해하는 데 결정적인 역할을 합니다. 구체적이고 맥락을 포함한 설명은 Claude의 동작을 효과적으로 안내합니다.

  • 입력 스키마: JSON Schema 형식으로 모든 매개변수를 정의하며, 타입 안전성과 명확한 문서를 제공합니다. required 필드, type 제약 조건, enum 열거형, default 값 및 description을 포함합니다. SDK는 이 스키마를 기반으로 들어오는 요청을 자동으로 검증합니다.

요청 처리

MCP 서버는 두 가지 유형의 요청에 응답합니다.

  • 도구 목록 요청 (ListToolsRequestSchema): Claude가 서버에 연결될 때 한 번 발생하며, 서버는 사용 가능한 모든 도구 정의 배열을 반환합니다.

  • 도구 호출 요청 (CallToolRequestSchema): Claude가 도구를 사용하고자 할 때 도구 이름과 인자(스키마에 따라 이미 유효성 검사됨)를 보냅니다. 서버는 switch 문 등을 사용하여 적절한 핸들러로 요청을 라우팅합니다.

인자 처리 및 보안

핸들러는 스키마에 따라 유효성 검사된 인자를 수신하지만, 특히 파일 경로 구성이나 시스템 명령 실행에 사용될 경우 추가적인 보안 유효성 검사가 필수적입니다. 예를 들어, preview_id에 대해 정규식(PREVIEW_ID_REGEX)을 사용하여 경로 탐색 공격(../../etc/passwd)을 방지해야 합니다. handleMermaidPreview 함수는 필수 및 선택적 인자를 추출하고, 보안 유효성 검사를 수행하며, 외부 도구(mmdc)를 실행하여 다이어그램을 렌더링하는 과정을 보여줍니다.

응답 형식

MCP 도구 응답은 표준 구조를 따릅니다. content 배열은 텍스트, 이미지 등 여러 정보를 반환할 수 있습니다. isError 플래그는 작업 실패 여부를 나타내며, Claude는 이를 통해 도구 호출 실패를 인지하고 사용자에게 알릴 수 있습니다.

여러 도구 노출

대부분의 MCP 서버는 여러 관련 도구를 노출합니다. claude-mermaid는 mermaid_preview (다이어그램 렌더링 및 미리보기)와 mermaid_save (렌더링된 다이어그램 파일로 저장) 두 가지 도구를 가집니다. 이는 사용자가 미리보기를 통해 다이어그램을 자유롭게 실험하고, 만족할 때만 저장하도록 하여 제어권을 부여합니다.

MCP 서버 디버깅

stdio 통신으로 인해 console.log()를 직접 사용할 수 없으므로, 파일 기반 로깅을 활용하는 것이 효과적입니다. 또한, 도구 핸들러에 대한 단위 테스트를 작성하여 MCP 프로토콜 전체를 실행하지 않고도 로직을 독립적으로 디버깅할 수 있습니다.

MCP 서버 배포

서버를 쉽게 설치할 수 있도록 package.json을 구성하고, 진입점 파일을 실행 가능하게 만들어야 합니다. 이후 npm install -g claude-mermaid로 설치하고 claude mcp add --scope user mermaid claude-mermaid 명령으로 Claude에 서버를 추가할 수 있습니다.

결론

MCP 서버 구축은 프로토콜 이해(stdio, ListTools, CallTool), 도구 정의(이름, 설명, JSON 스키마), 인자 처리(추출, 유효성 검사, 활용), 응답 형식(구조화된 콘텐츠, 성공/오류 상태) 및 보안(모든 입력 유효성 검사, 파일 접근 제한)에 대한 깊은 이해를 요구합니다. claude-mermaid의 전체 소스 코드는 이러한 개념을 다중 도구, 입력 유효성 검사, 파일 기반 로깅, 라이브 브라우저 미리보기와 같은 실제 구현에서 보여줍니다. 이러한 MCP의 기본 원칙들은 다이어그램 렌더러, 데이터베이스 쿼리 도구, API 통합 등 Claude를 위한 강력한 확장을 생성하는 데 필수적인 기반을 제공합니다.

관련 글들

Rails 애플리케이션에 MCP 서버 구축하기

MCP는 LLM이 외부 서비스와 표준화된 방식으로 상호작용하도록 돕는 개방형 프로토콜로, 애플리케이션 컨텍스트 제공을 통해 작업 효율성을 증대시킵니다.

11/25 읽어보기 →

Rails 애플리케이션에 MCP 서버를 추가하여 AI 통합하기

Rails 애플리케이션에 MCP(Model Context Protocol) 서버를 성공적으로 통합하여 AI 에이전트가 지원 요청을 자동화하고 처리할 수 있도록 구현했습니다.

05/06 읽어보기 →

FastMCP를 활용하여 Rails 앱을 AI 지원 MCP 서버로 전환하기

Model Context Protocol(MCP)은 AI 에이전트가 애플리케이션 도구와 구조적으로 상호작용하도록 돕는 개방형 표준입니다.

07/14 읽어보기 →

MCP 서버 구축 경험 보고서: 도전 과제와 전망

MCP(Model Context Protocol)는 AI 애플리케이션과 외부 시스템을 연결하는 오픈 소스 표준이나, 실제 구현에는 상당한 엔지니어링 노력이 요구됩니다.

01/24 읽어보기 →

댓글 0

로그인이 필요합니다

댓글을 작성하거나 대화에 참여하려면 로그인이 필요합니다.

로그인 하러 가기

아직 댓글이 없습니다

첫 번째 댓글을 작성해보세요!