byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

MCP 문서 · Tools

디버깅

Debugging · 원문: modelcontextprotocol.io/docs/tools/debugging

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

Model Context Protocol(MCP) 통합을 디버깅하는 종합 가이드

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

디버깅 도구 개요

MCP는 여러 수준의 디버깅을 위해 다음 도구를 제공합니다.

MCP Inspector: 대화형, 전송 방식에 무관한 테스트 UI입니다. stdio 또는 Streamable HTTP 서버에 연결하고, 도구, 프롬프트, 리소스를 호출하며, 알림 스트림을 관찰할 수 있습니다. 디버깅을 시작할 때 가장 먼저 사용하십시오.
서버 로깅: stdio 전송의 경우 stderr에 구조화된 로그를 출력하거나, 모든 전송 방식에서 notifications/message를 통해 로그를 전송합니다.
클라이언트 개발자 도구: 대부분의 MCP 클라이언트는 로그와 연결 상태를 노출합니다. 한 가지 예시로 아래의 Claude Desktop에서 디버깅하기를 참고하거나, 사용 중인 클라이언트의 문서를 확인하십시오.

로깅 구현

서버 측 로깅

로컬 stdio 전송을 사용하는 서버를 빌드할 때, stderr(표준 오류)에 기록된 모든 메시지는 호스트 애플리케이션에 의해 자동으로 캡처됩니다.

주의: 로컬 MCP 서버는 stdout(표준 출력)에 메시지를 기록해서는 안 됩니다. 이는 프로토콜 동작을 방해할 수 있습니다.

Streamable HTTP 전송을 사용하는 서버의 경우, stderr는 클라이언트에 의해 캡처되지 않습니다. 아래의 로그 메시지 알림, 자체 서버 측 로그 집계 시스템, 또는 표준 HTTP 도구(curl, 브라우저 DevTools Network 패널)를 사용해 요청, Mcp-Session-Id 헤더, SSE 스트림을 검사하십시오.

모든 전송 방식에서는 로그 메시지 알림을 전송해 클라이언트에 로그를 제공할 수도 있습니다.

코드 · 명령

@server.tool()
async def my_tool(ctx: Context) -> str:
    await ctx.session.send_log_message(
        level="info",
        data="Server started successfully",
    )
    return "done"

코드 · 명령

await server.sendLoggingMessage({
  level: "info",
  data: "Server started successfully",
});

MCP는 RFC 5424의 8가지 심각도 수준(debug부터 emergency까지)을 정의합니다. 클라이언트는 logging/setLevel 요청을 통해 런타임에서 최소 수준을 조정할 수 있습니다.

로깅이 중요한 이벤트 목록:

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

일반적인 문제

아래 예시는 Claude Desktop의 claude_desktop_config.json을 기준으로 합니다. 동일한 원칙이 모든 stdio 기반 MCP 클라이언트에 적용됩니다.

작업 디렉터리

MCP 클라이언트가 stdio 서버를 실행할 때:

클라이언트 설정을 통해 실행된 서버의 작업 디렉터리는 정의되지 않을 수 있습니다(macOS의 경우 /). 클라이언트가 어느 위치에서든 시작될 수 있기 때문입니다.
안정적인 동작을 보장하려면 설정 파일과 .env 파일에서 항상 절대 경로를 사용하십시오.
명령줄에서 서버를 직접 테스트하는 경우, 작업 디렉터리는 명령을 실행하는 위치가 됩니다.

예를 들어 claude_desktop_config.json에서는 다음과 같이 사용하십시오.

코드 · 명령

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/data"
      ]
    }
  }
}

./data와 같은 상대 경로 대신 절대 경로를 사용하십시오.

환경 변수

stdio를 통해 실행된 MCP 서버는 환경 변수의 제한된 하위 집합만 자동으로 상속합니다(정확한 집합은 플랫폼에 따라 다릅니다).

기본 변수를 재정의하거나 직접 변수를 제공하려면 claude_desktop_config.json에 env 키를 지정하십시오.

코드 · 명령

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

서버 초기화

일반적인 초기화 문제:

경로 문제 * 서버 실행 파일 경로가 잘못됨 * 필요한 파일이 없음 * 권한 문제 * command에 절대 경로를 사용해 보십시오.
설정 오류 * 잘못된 JSON 문법 * 필수 필드 누락 * 타입 불일치
환경 문제 * 환경 변수 누락 * 잘못된 변수 값 * 권한 제한

연결 문제

서버가 연결되지 않을 때:

클라이언트 로그 확인
서버 프로세스가 실행 중인지 확인
Inspector로 단독 테스트
프로토콜 호환성 확인
기능 협상(capability negotiation) 확인: 오류 코드 -32602는 표준 JSON-RPC "Invalid params" 코드로 여러 상황에서 반환됩니다. 흔한 원인 중 하나는 서버가 해당 기능을 선언하지 않은 클라이언트에 샘플링 또는 elicitation 요청을 보내는 경우입니다. initialize 교환을 검사해 양쪽이 기대하는 기능을 선언했는지 확인하십시오.

Claude Desktop에서 디버깅하기

Claude Desktop은 여러 MCP 클라이언트 중 하나입니다. macOS와 Windows에서 사용할 수 있습니다.

서버 상태 확인

채팅 입력창의 "파일, 커넥터 등 추가" 더하기 아이콘을 클릭한 후 Connectors 메뉴에 마우스를 올리면 연결된 서버와 사용 가능한 도구를 확인할 수 있습니다.

로그 보기

로그 파일은 다음 위치에 기록됩니다.

macOS: ~/Library/Logs/Claude
Windows: %APPDATA%\Claude\logs

코드 · 명령

# macOS
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

코드 · 명령

# Windows
type "$env:AppData\Claude\logs\mcp*.log"

로그에 캡처되는 항목:

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

Chrome DevTools 사용

Claude Desktop 내에서 Chrome 개발자 도구에 접근해 클라이언트 측 오류를 조사합니다.

allowDevTools를 true로 설정한 developer_settings.json 파일을 만드십시오.

코드 · 명령

# macOS
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json

코드 · 명령

# Windows
'{"allowDevTools": true}' | Set-Content "$env:AppData\Claude\developer_settings.json"

DevTools 열기: Command-Option-I(macOS) 또는 Ctrl+Alt+I(Windows)

참고: DevTools 창이 두 개 표시됩니다.

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

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

Network 패널에서 다음을 확인하십시오.

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

디버깅 워크플로

개발 사이클

초기 개발 * Inspector로 기본 테스트 * 핵심 기능 구현 * 로깅 포인트 추가
통합 테스트 * 대상 MCP 클라이언트에서 테스트 * 로그 모니터링 * 오류 처리 확인

변경 사항 테스트

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

설정 변경: MCP 클라이언트 재시작
서버 코드 변경: 클라이언트 재시작(Claude Desktop의 경우 완전히 종료 후 재시작; 창 닫기만으로는 부족합니다.)
빠른 반복: 개발 중에는 Inspector 사용

모범 사례

로깅 전략

구조화된 로깅 * 일관된 형식 사용 * 컨텍스트 포함 * 타임스탬프 추가 * 요청 ID 추적
오류 처리 * 스택 추적 로깅 * 오류 컨텍스트 포함 * 오류 패턴 추적 * 복구 모니터링
성능 추적 * 작업 시간 로깅 * 리소스 사용량 모니터링 * 메시지 크기 추적 * 지연 시간 측정

보안 고려 사항

디버깅 시:

민감한 데이터 * 로그 무결화(sanitize) * 자격 증명 보호 * 개인 정보 마스킹
접근 제어 * 권한 확인 * 인증 확인 * 접근 패턴 모니터링

MCP 공격 벡터 및 완화 방안에 대한 전체 내용은 보안 모범 사례를 참고하십시오.

도움 받기

문제가 발생했을 때:

첫 번째 단계 * 서버 로그 확인 * Inspector로 테스트 * 설정 검토 * 환경 확인
지원 채널 * GitHub 이슈 * GitHub 토론
제공할 정보 * 로그 발췌 * 설정 파일 * 재현 단계 * 환경 세부 정보

다음 단계

MCP Inspector — MCP Inspector 사용 방법을 학습합니다.
MCP 서버 빌드 — 서버를 처음부터 빌드하는 과정을 따라갑니다.
로컬 서버 연결 — claude_desktop_config.json 전체 참고 및 문제 해결

원문(영어): https://modelcontextprotocol.io/docs/tools/debugging · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Model Context Protocol)에게 있습니다.

원문(영어): https://modelcontextprotocol.io/docs/tools/debugging

문서 이동

‹ SDK MCP Inspector › · 전체 목차