1. 什么是日志？ #

日志（Logging）是 MCP 服务器向客户端发送结构化日志消息的标准化方式。客户端可设置最低日志级别，服务器只发送该级别及以上的日志，便于调试、排错和监控。

协议版本：2025-11-25

2. 本章你将学到 #

• 日志的能力声明与协议消息
• 如何设置日志级别、接收日志通知
• 日志级别含义与示例
• 错误处理、实现建议与安全要点

3. 典型流程 #

客户端连接服务器后，发送 logging/setLevel 将级别设为 info → 服务器执行操作时，通过 notifications/message 推送 info、warning、error 等日志 → 客户端在控制台或 UI 中展示。若用户只需关注错误，可将级别改为 error，服务器仅发送 error 及以上级别。

4. 能力 #

服务器必须声明 logging 能力：

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

5. 日志级别 #

遵循 RFC 5424 标准 syslog 严重级别，从低到高：

6. 协议消息 #

6.1 设置日志级别（logging/setLevel） #

客户端可以发送此请求，控制接收哪些级别的日志：

请求：

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

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}

6.2 日志消息通知（notifications/message） #

服务器通过通知推送日志，客户端不需回复：

示例：error 级别

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

示例：info 级别

{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "info",
    "logger": "tools",
    "data": {
      "message": "Tool get_weather called",
      "args": { "location": "Paris" }
    }
  }
}

示例：debug 级别（仅当客户端设 debug 时收到）

{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "debug",
    "logger": "parser",
    "data": { "step": "parse_input", "raw": "..." }
  }
}

7. 流程示意 #

8. 错误处理 #

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid log level: invalid_level"
  }
}

9. 实现建议 #

10. 安全要点 #