디버깅

MCP 서버를 개발하거나 애플리케이션에 통합할 때, 효과적인 디버깅은 필수입니다. 이 가이드는 MCP 생태계에서 사용할 수 있는 디버깅 도구와 접근 방법을 다룹니다.

이 가이드는 macOS 기준으로 작성되었습니다. 다른 플랫폼용 가이드는 곧 추가될 예정입니다.

디버깅 도구 개요

MCP는 다양한 수준에서 디버깅할 수 있도록 여러 도구를 제공합니다:

  1. MCP Inspector

    • 대화형 디버깅 인터페이스
    • 서버를 직접 테스트
    • 자세한 내용은 인스펙터 가이드를 참고하세요.

  2. Claude Desktop Developer Tools

    • 통합 테스트
    • 로그 수집
    • Chrome DevTools 연동

  3. Server Logging

    • 커스텀 로깅 구현
    • 오류 추적
    • 성능 모니터링

Claude Desktop에서 디버깅하기

서버 상태 확인

Claude.app UI에서 기본적인 서버 상태 정보를 확인할 수 있습니다:

  1. <img src="/images/claude-desktop-mcp-plug-icon.svg" style={{display: ‘inline’, margin: 0, height: ‘1.3em’}} /> 아이콘을 클릭하면 다음을 볼 수 있습니다:

    • 연결된 서버
    • 사용 가능한 프롬프트 및 리소스

  2. <img src="/images/claude-desktop-mcp-hammer-icon.svg" style={{display: ‘inline’, margin: 0, height: ‘1.3em’}} /> 아이콘을 클릭하면 다음을 볼 수 있습니다:

    • 모델에 노출된 도구

로그 확인

Claude Desktop에서 상세 MCP 로그를 확인하세요:

# Follow logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

로그에는 다음이 기록됩니다:

  • 서버 연결 이벤트
  • 설정 문제
  • 런타임 오류
  • 메시지 교환

Chrome DevTools 사용

Claude Desktop 안에서 Chrome 개발자 도구를 열어 클라이언트 측 오류를 조사할 수 있습니다:

  1. DevTools 활성화:
jq '.allowDevTools = true' ~/Library/Application\ Support/Claude/developer_settings.json > tmp.json \
  && mv tmp.json ~/Library/Application\ Support/Claude/developer_settings.json
  1. DevTools 열기: Command-Option-Shift-i

참고: DevTools 창이 두 개 뜰 수 있습니다:

  • 메인 콘텐츠 창
  • 앱 타이틀 바 창

Console 패널에서 클라이언트 측 오류를 확인하세요.

Network 패널에서 아래를 확인할 수 있습니다:

  • 메시지 페이로드
  • 연결 타이밍

자주 발생하는 문제

환경 변수

MCP 서버는 기본적으로 USER, HOME, PATH 같은 일부 환경 변수만 자동으로 상속합니다.

기본 환경 변수를 덮어쓰거나 추가 환경 변수를 전달하려면 claude_desktop_config.json에서 env 키를 지정할 수 있습니다:

{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}

서버 초기화

서버 초기화에서 흔히 발생하는 문제:

  1. 경로 문제

    • 서버 실행 파일 경로 오류
    • 필수 파일 누락
    • 권한 문제

  2. 설정 오류

    • JSON 문법 오류
    • 필수 필드 누락
    • 타입 불일치

  3. 환경 문제

    • 환경 변수 누락
    • 환경 변수 값 오류
    • 권한 제한

연결 문제

서버 연결이 실패할 때는:

  1. Claude Desktop 로그 확인
  2. 서버 프로세스가 실행 중인지 확인
  3. 인스펙터로 단독 테스트
  4. 프로토콜 호환성 확인

로깅 구현

서버 측 로깅

로컬 stdio 전송(transport)을 사용하는 서버를 만들 경우, stderr(표준 오류)에 기록한 모든 메시지는 호스트 애플리케이션(예: Claude Desktop)이 자동으로 수집합니다.

로컬 MCP 서버는 stdout(표준 출력)에 로그를 남기면 프로토콜 동작을 방해할 수 있으므로 stdout에는 로그를 출력하지 마세요.

모든 전송(transport)에서, 로그 메시지 알림(notification)을 보내 클라이언트에 로그를 전달할 수도 있습니다:

```python server.request_context.session.send_log_message( level="info", data="Server started successfully", ) ``` ```typescript server.sendLoggingMessage({ level: "info", data: "Server started successfully", }); ```

기록을 권장하는 주요 이벤트:

  • 초기화 단계
  • 리소스 접근
  • 도구 실행
  • 오류 상황
  • 성능 지표

클라이언트 측 로깅

클라이언트 애플리케이션에서는:

  1. 디버그 로깅 활성화
  2. 네트워크 트래픽 모니터링
  3. 메시지 교환 추적
  4. 오류 상태 기록

디버깅 워크플로

개발 사이클

  1. 초기 개발

    • 기본 테스트는 인스펙터 사용
    • 핵심 기능 구현
    • 로깅 지점 추가

  2. 통합 테스트

    • Claude Desktop에서 테스트
    • 로그 모니터링
    • 오류 처리 확인

변경 사항 테스트

변경 사항을 효율적으로 테스트하려면:

  • 설정 변경: Claude Desktop 재시작
  • 서버 코드 변경: Command-R로 리로드
  • 빠른 반복: 개발 중에는 인스펙터 활용

모범 사례

로깅 전략

  1. 구조화된 로깅

    • 일관된 포맷 사용
    • 컨텍스트 포함
    • 타임스탬프 추가
    • 요청 ID 추적

  2. 오류 처리

    • 스택 트레이스 로깅
    • 오류 컨텍스트 포함
    • 오류 패턴 추적
    • 복구 동작 모니터링

  3. 성능 추적

    • 작업 소요 시간 로깅
    • 리소스 사용량 모니터링
    • 메시지 크기 추적
    • 지연 시간 측정

보안 고려사항

디버깅 시에는:

  1. 민감 정보

    • 로그에서 민감 정보 제거/마스킹
    • 자격 증명 보호
    • 개인 정보 마스킹

  2. 접근 제어

    • 권한 검증
    • 인증 확인
    • 접근 패턴 모니터링

도움 받기

문제가 발생했을 때:

  1. 우선 확인

    • 서버 로그 확인
    • 인스펙터로 테스트
    • 설정 검토
    • 환경 확인

  2. 지원 채널

    • GitHub Issues
    • GitHub Discussions

  3. 공유하면 좋은 정보

    • 로그 일부
    • 설정 파일
    • 재현 절차
    • 환경 정보

다음 단계

MCP 인스펙터 사용법을 익히세요.