Logging

Protocol Revision: draft

The Model Context Protocol (MCP) provides a standardized way for servers to send structured log messages to clients. Clients can control logging verbosity by setting minimum log levels, with servers sending notifications containing severity levels, optional logger names, and arbitrary JSON-serializable data.

User Interaction Model

Implementations are free to expose logging through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model.

Capabilities

Servers that emit log message notifications MUST declare the logging capability:

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

Log Levels

The protocol follows the standard syslog severity levels specified in RFC 5424:

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

Protocol Messages

Setting Log Level

To configure the minimum log level, clients MAY send a logging/setLevel request:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "logging/setLevel",
  "params": {
    "level": "info"
  }
}

Log Message Notifications

Servers send log messages using notifications/message notifications:

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

Message Flow

  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

Error Handling

Servers SHOULD return standard JSON-RPC errors for common failure cases:

Ungültige Logstufe: -32602 (Invalid params)
Konfigurationsfehler: -32603 (Internal error)

Implementation Considerations

Server SOLLEN:
- Log‑Nachrichten rate‑limiten
- Relevanten Kontext im Datenfeld beifügen
- Konsistente Logger‑Namen verwenden
- Sensible Informationen entfernen
Clients DÜRFEN:
- Log‑Nachrichten in der UI darstellen
- Log‑Filterung/Suche implementieren
- Schweregrad visuell anzeigen
- Log‑Nachrichten persistieren

Security

Log‑Nachrichten DÜRFEN NICHT enthalten:
- Zugangsdaten oder Geheimnisse
- Personenbeziehbare Informationen
- Interne Systemdetails, die Angriffe begünstigen könnten
Implementierungen SOLLEN:
- Nachrichten rate‑limiten
- Alle Datenfelder validieren
- Zugriff auf Logs kontrollieren
- Auf sensible Inhalte überwachen

Completion Pagination