로깅

로깅 (Logging)

서버가 구조화된 로그 메시지를 클라이언트에게 보내는 표준화된 방법을 설명하는 페이지예요. 클라이언트는 _meta를 통해 요청별 로그 상세도를 통제하고, 서버는 심각도 레벨·선택적 로거 이름·임의의 JSON 직렬화 데이터를 담은 알림을 보내요. 이 기능은 **폐기(Deprecated)**되었어요.

출처: 문서

본문

경고 (Warning): Deprecated: Logging 기능은 프로토콜 버전 2026-07-28 기준으로 폐기되었어요 (SEP-2577). 기능 수명주기 정책 아래에서 이 개정이 릴리스된 후 최소 12개월 동안 사양에 남아 있다가 제거 자격을 얻어요. 새 구현은 SHOULD NOT 이를 채택하고, 기존 구현은 stdio 트랜스포트에서는 stderr로, 구조화된 관측성(structured observability)에는 OpenTelemetry로 로깅하는 방식으로 SHOULD 이전해야 해요. 폐기 기능 레지스트리를 참조하세요.

Model Context Protocol (MCP)은 서버가 구조화된 로그 메시지를 클라이언트에게 보내는 표준화된 방법을 제공해요. 클라이언트는 _meta를 통해 요청별 로그 상세도(verbosity)를 통제하고, 서버는 심각도 레벨·선택적 로거 이름·임의의 JSON 직렬화 가능 데이터를 담은 알림을 보내요.

사용자 상호작용 모델 (User Interaction Model)

구현자는 자신의 필요에 맞는 어떤 인터페이스 패턴으로든 로깅을 노출할 자유가 있어요. 프로토콜 자체는 특정 사용자 상호작용 모델을 강제하지 않아요.

기능 (Capabilities)

로그 메시지 알림을 내보내는 서버는 MUST logging 기능을 선언해야 해요:

{
  "capabilities": {
    "logging": {}
  }
}

로그 레벨 (Log Levels)

프로토콜은 RFC 5424에 명시된 표준 syslog 심각도 레벨을 따라요:

Level	Description	Example Use Case
debug	Detailed debugging information	Function entry/exit points
info	General informational messages	Operation progress updates
notice	Normal but significant events	Configuration changes
warning	Warning conditions	Deprecated feature usage
error	Error conditions	Operation failures
critical	Critical conditions	System component failures
alert	Action must be taken immediately	Data corruption detected
emergency	System is unusable	Complete system failure

로그 메시지 요청 (Requesting Log Messages)

요청별 로그 레벨 (Per-request log level)

특정 요청에 대한 로그 메시지를 받으려면 요청의 _meta에 io.modelcontextprotocol/logLevel을 포함해요. 서버는 MUST NOT 이 필드를 포함하지 않은 요청에 대해 notifications/message를 내보내면 안 돼요.

필드가 있으면 서버는 MAY 그 요청의 응답 스트림에서, 최종 응답 전에 요청된 레벨 이상의 notifications/message 알림을 보낼 수 있어요. notifications/message는 요청 범위(request-scoped)예요. 서버는 MUST NOT 이를 subscriptions/listen 스트림이나, 로그 레벨을 설정한 요청에 대한 응답을 나르는 스트림 이외의 어떤 스트림에서도 전달해서는 안 돼요.

프로토콜 메시지 (Protocol Messages)

로그 메시지 알림 (Log Message Notifications)

서버는 notifications/message 알림으로 로그 메시지를 보내요:

{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "error",
    "logger": "database",
    "data": {
      "error": "Connection failed",
      "details": {
        "host": "localhost",
        "port": 5432
      }
    }
  }
}

오류 처리 (Error Handling)

요청의 _meta에 담긴 io.modelcontextprotocol/logLevel 값이 인식되지 않는 로그 레벨이면, 서버는 SHOULD 표준 JSON-RPC 오류로 그 요청을 거부해야 해요:

유효하지 않은 로그 레벨: -32602 (Invalid params)
내부 오류: -32603 (Internal error)

구현 고려 사항 (Implementation Considerations)

서버는 SHOULD:
- 로그 메시지에 비율 제한을 적용한다
- data 필드에 관련 컨텍스트를 포함한다
- 일관된 로거 이름을 사용한다
- 민감한 정보를 제거한다
클라이언트는 MAY:
- UI에 로그 메시지를 표시할 수 있다
- 로그 필터링/검색을 구현할 수 있다
- 심각도를 시각적으로 표시할 수 있다
- 로그 메시지를 유지할 수 있다

보안 (Security)

로그 메시지는 MUST NOT 담으면 안 된다:
- 자격 증명이나 비밀
- 개인 식별 정보
- 공격을 도울 수 있는 내부 시스템 세부 사항
구현은 SHOULD:
- 메시지에 비율 제한을 적용한다
- 모든 데이터 필드를 검증한다
- 로그 접근을 통제한다
- 민감한 콘텐츠를 모니터링한다

로깅