日志记录

• 1 用户交互模型
• 2 能力
• 3 日志级别
• 4 协议消息
  • 4.1 设置日志级别
  • 4.2 日志消息通知
• 5 消息流程
• 6 错误处理
• 7 实现注意事项
• 8 安全

协议版本: 2025-11-25

模型上下文协议（MCP）为服务器向客户端发送结构化日志消息提供了标准化方式。客户端可以通过设置最低日志级别来控制日志详细程度，服务器发送包含严重级别、可选记录器名称和任意 JSON 可序列化数据的通知。

1 用户交互模型

实现可以通过任何适合其需求的界面模式公开日志记录——协议本身不强制要求任何特定的用户交互模型。

2 能力

发出日志消息通知的服务器必须声明 logging 能力：

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

3 日志级别

协议遵循 RFC 5424 中指定的标准 syslog 严重级别：

级别	描述	示例用例
debug	详细调试信息	函数入口/出口点
info	一般信息性消息	操作进度更新
notice	正常但重要的事件	配置更改
warning	警告条件	弃用功能使用
error	错误条件	操作失败
critical	关键条件	系统组件故障
alert	必须立即采取行动	检测到数据损坏
emergency	系统不可用	完全系统故障

4 协议消息

4.1 设置日志级别

要配置最低日志级别，客户端可以发送 logging/setLevel 请求：

请求：

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

4.2 日志消息通知

服务器使用 notifications/message 通知发送日志消息：

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

5 消息流程

6 错误处理

服务器应该为常见故障情况返回标准 JSON-RPC 错误：

• 无效日志级别：-32602（无效参数）
• 配置错误：-32603（内部错误）

7 实现注意事项

1. 服务器应该：

   • 对日志消息进行速率限制
   • 在数据字段中包含相关上下文
   • 使用一致的记录器名称
   • 删除敏感信息

2. 客户端可以：

   • 在 UI 中显示日志消息
   • 实现日志过滤/搜索
   • 可视化显示严重级别
   • 持久化日志消息

8 安全

1. 日志消息禁止包含：

   • 凭据或机密
   • 个人识别信息
   • 可能帮助攻击的内部系统详情

2. 实现应该：

   • 对消息进行速率限制
   • 验证所有数据字段
   • 控制日志访问
   • 监控敏感内容