Model Context Protocol(MCP) 통합 디버깅을 위한 포괄적인 가이드
효과적인 디버깅은 MCP 서버를 개발하거나 애플리케이션과 통합할 때 필수적입니다. 이 가이드는 MCP 생태계에서 사용할 수 있는 디버깅 도구와 접근 방식을 다룹니다.
이 가이드는 macOS용입니다. 다른 플랫폼을 위한 가이드는 곧 제공될 예정입니다.
디버깅 도구 개요
MCP는 다양한 수준에서 디버깅을 위한 여러 도구를 제공합니다:
- MCP Inspector
- 대화형 디버깅 인터페이스
- 직접 서버 테스트
- 자세한 내용은 Inspector 가이드 참조
- Claude Desktop 개발자 도구
- 통합 테스트
- 로그 수집
- Chrome DevTools 통합
- 서버 로깅
- 사용자 정의 로깅 구현
- 오류 추적
- 성능 모니터링
Claude Desktop에서의 디버깅
서버 상태 확인
Claude.app 인터페이스는 기본적인 서버 상태 정보를 제공합니다:
- 아이콘을 클릭하여 다음을 볼 수 있습니다:
- 연결된 서버
- 사용 가능한 프롬프트 및 리소스
- 아이콘을 클릭하여 다음을 볼 수 있습니다:
- 모델에서 사용 가능한 도구
로그 보기
Claude Desktop에서 자세한 MCP 로그를 검토하세요:
# 실시간으로 로그 팔로우
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log로그는 다음을 캡처합니다:
- 서버 연결 이벤트
- 구성 문제
- 런타임 오류
- 메시지 교환
Chrome DevTools 사용
Claude Desktop 내에서 Chrome의 개발자 도구에 접근하여 클라이언트 측 오류를 조사하세요:
allowDevTools를 true로 설정한developer_settings.json파일을 생성하세요:
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json- DevTools 열기:
Command-Option-Shift-i
참고: 두 개의 DevTools 창이 표시됩니다:
- 메인 콘텐츠 창
- 앱 제목 표시줄 창
콘솔 패널을 사용하여 클라이언트 측 오류를 검사하세요.
네트워크 패널을 사용하여 다음을 검사하세요:
- 메시지 페이로드
- 연결 타이밍
일반적인 문제
작업 디렉토리
Claude Desktop에서 MCP 서버를 사용할 때:
claude_desktop_config.json을 통해 실행된 서버의 작업 디렉토리는 정의되지 않을 수 있습니다(macOS에서는/와 같이). Claude Desktop은 어디에서든 시작될 수 있기 때문입니다.- 안정적인 작동을 위해 구성 및
.env파일에 항상 절대 경로를 사용하세요. - 명령줄을 통해 직접 서버를 테스트하는 경우, 작업 디렉토리는 명령을 실행하는 위치가 됩니다.
예를 들어 claude_desktop_config.json에서는 다음과 같이 사용하세요:
{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}./data와 같은 상대 경로 대신 절대 경로를 사용하세요.
환경 변수
MCP 서버는 USER, HOME, PATH와 같은 환경 변수의 하위 집합만 자동으로 상속받습니다.
기본 변수를 재정의하거나 자체 변수를 제공하려면 claude_desktop_config.json에서 env 키를 지정할 수 있습니다:
{
"myserver": {
"command": "mcp-server-myapp",
"env": {
"MYAPP_API_KEY": "some_key",
}
}
}서버 초기화
일반적인 초기화 문제:
- 경로 문제
- 잘못된 서버 실행 파일 경로
- 필요한 파일 누락
- 권한 문제
command에 절대 경로 사용 시도
- 구성 오류
- 잘못된 JSON 구문
- 필수 필드 누락
- 타입 불일치
- 환경 문제
- 환경 변수 누락
- 잘못된 변수 값
- 권한 제한
연결 문제
서버가 연결에 실패할 때:
- Claude Desktop 로그 확인
- 서버 프로세스가 실행 중인지 확인
- Inspector로 독립 테스트
- 프로토콜 호환성 확인
로깅 구현
서버 측 로깅
로컬 stdio 전송을 사용하는 서버를 구축할 때, stderr(표준 오류)에 기록된 모든 메시지는 호스트 애플리케이션(예: Claude Desktop)에 의해 자동으로 캡처됩니다.
로컬 MCP 서버는 프로토콜 작업에 간섭할 수 있으므로 stdout(표준 출력)에 메시지를 기록해서는 안 됩니다.
모든 전송에서 로그 메시지 알림을 보내 클라이언트에 로깅을 제공할 수도 있습니다:
- Python
- TypeScript
server.request_context.session.send_log_message(
level="info",
data="Server started successfully",
)server.sendLoggingMessage({
level: "info",
data: "Server started successfully",
});로깅할 중요한 이벤트:
- 초기화 단계
- 리소스 액세스
- 도구 실행
- 오류 상태
- 성능 지표
클라이언트 측 로깅
클라이언트 애플리케이션에서:
- 디버그 로깅 활성화
- 네트워크 트래픽 모니터링
- 메시지 교환 추적
- 오류 상태 기록
디버깅 워크플로우
개발 주기
- 초기 개발
- 기본 테스트를 위해 Inspector 사용
- 핵심 기능 구현
- 로깅 포인트 추가
- 통합 테스트
- Claude Desktop에서 테스트
- 로그 모니터링
- 오류 처리 확인
변경 사항 테스트
변경 사항을 효율적으로 테스트하려면:
- 구성 변경: Claude Desktop 재시작
- 서버 코드 변경: Command-R을 사용하여 다시 로드
- 빠른 반복: 개발 중에 Inspector 사용
모범 사례
로깅 전략
- 구조화된 로깅
- 일관된 형식 사용
- 컨텍스트 포함
- 타임스탬프 추가
- 요청 ID 추적
- 오류 처리
- 스택 트레이스 로깅
- 오류 컨텍스트 포함
- 오류 패턴 추적
- 복구 모니터링
- 성능 추적
- 작업 타이밍 로깅
- 리소스 사용량 모니터링
- 메시지 크기 추적
- 지연 시간 측정
보안 고려사항
디버깅 시:
- 민감한 데이터
- 로그 정리
- 자격 증명 보호
- 개인 정보 마스킹
- 접근 제어
- 권한 확인
- 인증 확인
- 접근 패턴 모니터링
도움 받기
문제가 발생했을 때:
- 첫 번째 단계
- 서버 로그 확인
- Inspector로 테스트
- 구성 검토
- 환경 확인
- 지원 채널
- GitHub 이슈
- GitHub 토론
- 정보 제공
- 로그 발췌
- 구성 파일
- 재현 단계
- 환경 세부 정보
다음 단계
MCP Inspector 사용법 알아보기
