디버깅

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

디버깅 도구 개요

MCP는 여러 계층에서 문제를 진단할 수 있는 도구를 제공합니다.

1. MCP Inspector: 대화형이며 트랜스포트에 구애받지 않는 테스트 UI입니다. stdio 또는 Streamable HTTP 서버에 연결하여 도구, 프롬프트, 리소스를 호출하고 알림 스트림을 관찰할 수 있습니다. 문제를 진단할 때 가장 먼저 사용해 보세요.
2. 서버 로깅: stderr(stdio 트랜스포트) 또는 OpenTelemetry(모든 트랜스포트)를 통해 구조화된 로그를 기록합니다. 프로토콜의 로깅 (notifications/message)은 프로토콜 버전 2026-07-28부터 더 이상 사용되지 않습니다.
3. 클라이언트 개발자 도구: 대부분의 MCP 클라이언트는 로그와 연결 상태를 제공합니다. 한 가지 예로 아래의 Claude Desktop에서 디버깅하기를 참고하거나 사용 중인 클라이언트의 문서를 확인하세요.

로깅 구현

서버 측 로깅

로컬 stdio 트랜스포트를 사용하는 서버를 구축하면 stderr(표준 오류)에 기록된 모든 메시지를 호스트 애플리케이션이 자동으로 수집합니다.

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

Streamable HTTP 트랜스포트를 사용하는 서버에서는 클라이언트가 stderr를 수집하지 않습니다. 로그에는 자체 서버 측 로그 집계 시스템이나 OpenTelemetry를 사용하고, 요청과 SSE 스트림을 검사할 때는 일반적인 HTTP 도구(curl, 브라우저 DevTools의 Network 패널)를 사용하세요.

아래의 notifications/message 메커니즘은 프로토콜 버전 2026-07-28부터 더 이상 사용되지 않습니다. 지원 중단 유예 기간에는 계속 사용할 수 있습니다.

모든 트랜스포트에서 서버가 실행 중 수행하는 작업을 기록하세요.

import logging

from mcp.server import MCPServer

logger = logging.getLogger(__name__)

mcp = MCPServer("reports")


@mcp.tool()
async def fetch_report(report_id: str) -> str:
    """Fetch a report by id."""
    logger.info("Fetching report %s", report_id)
    return f"Report {report_id} is ready."

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

MCP는 debug부터 emergency까지 여덟 가지 RFC 5424 심각도 수준을 정의합니다. 클라이언트는 요청의 _meta에 io.modelcontextprotocol/logLevel 필드를 설정하여 요청별 로그 메시지 수신을 선택합니다. 서버는 이 필드가 없는 요청에 notifications/message를 전송해서는 안 됩니다.

로그로 기록해야 할 주요 이벤트는 다음과 같습니다.

• 시작 단계
• 리소스 접근
• 도구 실행
• 오류 상태
• 성능 지표

일반적인 문제

아래 예제에서는 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"
      }
    }
  }
}

서버 시작

일반적인 서버 시작 문제는 다음과 같습니다.

1. 경로 관련 문제

   • 잘못된 서버 실행 파일 경로
   • 필요한 파일이 누락됨
   • 권한 문제
   • command에 절대 경로를 사용해 보세요.

2. 설정 오류

   • 유효하지 않은 JSON 구문
   • 필요한 필드가 누락됨
   • 데이터 타입 불일치

3. 환경 관련 문제

   • 환경 변수가 누락됨
   • 변수 값이 잘못됨
   • 권한 제한

연결 관련 문제

서버 연결에 실패하면 다음을 확인하세요.

1. 클라이언트 로그를 확인합니다.
2. 서버 프로세스가 실행 중인지 확인합니다.
3. Inspector로 서버를 단독 테스트합니다.
4. 프로토콜 호환성을 확인합니다. server/discover를 호출하면 서버가 지원하는 프로토콜 버전을 확인할 수 있습니다. UnsupportedProtocolVersionError (-32022)의 data 필드에는 서버가 지원하는 버전이 나열됩니다.
5. 요청별 _meta 필드를 확인합니다. 모든 요청에는 io.modelcontextprotocol/protocolVersion과 io.modelcontextprotocol/clientCapabilities가 있어야 하며, 클라이언트는 io.modelcontextprotocol/clientInfo도 포함하는 것이 좋습니다. 두 필수 필드 중 하나라도 없으면 요청은 오류 -32602 (Invalid params)로 거부됩니다. 이 코드는 형식이 잘못된 여러 다른 입력에도 사용됩니다. 서버에 필요한 기능(예: 사용자 입력 요청)을 요청의 clientCapabilities가 선언하지 않았다면, 서버는 누락된 기능의 이름을 담은 MissingRequiredClientCapabilityError (-32021)를 반환합니다. 요청의 _meta와 server/discover 응답을 검사하여 양측이 예상한 내용을 모두 선언했는지 확인하세요.

Claude Desktop에서의 디버깅

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

서버 상태 확인

채팅 입력란에서 "Add files, connectors, and more" 플러스 아이콘을 클릭한 다음 Connectors 메뉴 위에 마우스를 올리면 연결된 서버와 사용 가능한 도구를 확인할 수 있습니다.

로그 보기

로그 파일은 다음 위치에 저장됩니다.

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

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

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

로그에는 다음 정보가 기록됩니다.

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

Chrome DevTools 사용

Claude Desktop 내부의 Chrome 개발자 도구에서 클라이언트 측 오류를 조사할 수 있습니다.

1. allowDevTools를 true로 설정한 developer_settings.json 파일을 만듭니다.

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

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

2. Command-Option-I(macOS) 또는 Ctrl+Alt+I(Windows)를 눌러 DevTools를 엽니다.

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

• 메인 콘텐츠 창
• 앱 제목 표시줄 창

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

Network 패널에서는 다음 항목을 확인할 수 있습니다.

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

디버깅 워크플로

개발 주기

1. 초기 개발

   • Inspector로 기본 테스트를 수행합니다.
   • 핵심 기능을 구현합니다.
   • 로깅 지점을 추가합니다.

2. 통합 테스트

   • 대상 MCP 클라이언트에서 테스트합니다.
   • 로그를 모니터링합니다.
   • 오류 처리를 점검합니다.

변경 사항 테스트

변경 사항을 효율적으로 테스트하려면 다음 지침을 따르세요.

• 구성 변경: MCP 클라이언트를 재시작합니다.
• 서버 코드 변경: 클라이언트를 재시작해야 합니다(Claude Desktop의 경우에는 프로그램을 완전히 종료한 후 다시 실행해야 하며, 단순히 창을 닫는 것만으로는 충분하지 않습니다).
• 신속한 반복 개발: 개발 과정에서 Inspector를 사용합니다.

모범 사례

로깅 전략

1. 구조화된 로깅

   • 일관된 형식을 사용합니다.
   • 상황 정보를 포함합니다.
   • 타임스탬프를 추가합니다.
   • 요청 ID를 추적합니다.

2. 오류 처리

   • 스택 트레이스를 기록합니다.
   • 오류와 관련된 상황 정보를 포함합니다.
   • 오류 패턴을 추적합니다.
   • 복구 과정을 모니터링합니다.

3. 성능 추적

   • 작업 실행 시간을 기록합니다.
   • 리소스 사용량을 모니터링합니다.
   • 메시지 크기를 추적합니다.
   • 지연 시간을 측정합니다.

보안 고려 사항

디버깅을 수행할 때:

1. 민감한 데이터

   • 로그를 정제합니다.
   • 자격 증명을 보호합니다.
   • 개인 정보를 가리웁니다.

2. 접근 제어

   • 권한을 확인합니다.
   • 인증 상태를 점검합니다.
   • 접근 패턴을 모니터링합니다.

MCP의 공격 벡터와 완화 방안을 자세히 알아보려면 보안 모범 사례를 참고하세요.

도움 받기

문제가 발생하면 다음을 확인하세요.

1. 초기 조치

   • 서버 로그를 확인합니다.
   • Inspector를 사용하여 테스트합니다.
   • 구성 설정을 검토합니다.
   • 실행 환경을 확인합니다.

2. 지원 채널

   • GitHub 이슈
   • GitHub 토론

3. 정보 제공

   • 로그의 일부 내용
   • 구성 파일
   • 문제 재현을 위한 단계
   • 환경에 대한 상세 정보

다음 단계

◇MCP Inspector

MCP Inspector의 사용 방법을 익힙니다.

→

◇MCP 서버 구축

처음부터 서버를 구축하는 과정을 단계별로 안내합니다.

→

◇로컬 서버 연결

claude_desktop_config.json의 전체 참고 자료와 문제 해결 방법을 확인합니다.

→