byteforce

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

MCP 문서 · Specification

로깅

Logging · 원문: modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging

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

MCP(Model Context Protocol)는 서버가 클라이언트에 구조화된 로그 메시지를 보내기 위한 표준화된 방법을 제공합니다. 클라이언트는 최소 로그 레벨을 설정하여 로깅 상세도를 제어할 수 있으며, 서버는 심각도 레벨, 선택적 로거 이름, 임의의 JSON 직렬화 가능한 데이터를 포함하는 알림을 보냅니다.

사용자 상호작용 모델

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

기능(Capabilities)

로그 메시지 알림을 내보내는 서버는 logging 기능을 반드시 선언해야 합니다(MUST).

코드 · 명령
{
  "capabilities": {
    "logging": {}
  }
}

로그 레벨

프로토콜은 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

프로토콜 메시지

로그 레벨 설정

최소 로그 레벨을 구성하기 위해 클라이언트는 logging/setLevel 요청을 보낼 수 있습니다(MAY).

요청:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "logging/setLevel",
  "params": {
    "level": "info"
  }
}

로그 메시지 알림

서버는 notifications/message 알림을 사용하여 로그 메시지를 보냅니다.

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

메시지 흐름

코드 · 명령
sequenceDiagram
    participant Client
    participant Server

    Note over Client,Server: Configure Logging
    Client->>Server: logging/setLevel (info)
    Server-->>Client: Empty Result

    Note over Client,Server: Server Activity
    Server--)Client: notifications/message (info)
    Server--)Client: notifications/message (warning)
    Server--)Client: notifications/message (error)

    Note over Client,Server: Level Change
    Client->>Server: logging/setLevel (error)
    Server-->>Client: Empty Result
    Note over Server: Only sends error level<br/>and above

오류 처리

서버는 일반적인 실패 사례에 대해 표준 JSON-RPC 오류를 반환해야 합니다(SHOULD).

구현 고려 사항

  1. 서버는 다음을 수행해야 합니다(SHOULD). * 로그 메시지 속도 제한 * data 필드에 관련 컨텍스트 포함 * 일관된 로거 이름 사용 * 민감한 정보 제거

  2. 클라이언트는 다음을 수행할 수 있습니다(MAY). * UI에 로그 메시지 표시 * 로그 필터링/검색 구현 * 심각도를 시각적으로 표시 * 로그 메시지 지속

보안

  1. 로그 메시지에는 다음 항목을 포함해서는 안 됩니다(MUST NOT). * 자격 증명 또는 비밀 * 개인 식별 정보 * 공격에 도움이 될 수 있는 내부 시스템 세부 정보

  2. 구현체는 다음을 수행해야 합니다(SHOULD). * 메시지 속도 제한 * 모든 데이터 필드 검증 * 로그 접근 제어 * 민감한 콘텐츠 모니터링

원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Model Context Protocol)에게 있습니다.

원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging