> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 日志

<div id="enable-section-numbers" />

<Warning>
  **已弃用**：自协议版本
  `2026-07-28`
  ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)) 起，Logging 功能已被弃用。
  根据[功能生命周期政策](/community/feature-lifecycle)，在本次修订发布后至少十二个月内，它仍保留在规范中，之后才会符合移除条件。新的实现 **不应该** 采用它；现有实现 **应该** 迁移到将日志记录到 `stderr`（适用于 stdio 传输），或迁移到 [OpenTelemetry](https://opentelemetry.io/)（适用于结构化可观测性）。参见[已弃用功能注册表](/specification/draft/deprecated)。
</Warning>

Model Context Protocol（MCP）为服务器向客户端发送结构化日志消息提供了一种标准化方式。客户端通过 `_meta` 按请求控制日志详细程度，而服务器会发送包含严重性级别、可选记录器名称以及任意可 JSON 序列化数据的通知。

## 用户交互模型

实现可以通过任何适合其需求的接口模式暴露日志—协议本身并不强制要求任何特定的用户交互模型。

## 能力

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

```json theme={null}
{
  "capabilities": {
    "logging": {}
  }
}
```

## 日志级别

协议遵循 [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1) 中指定的标准 syslog 严重性级别：

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

## 请求日志消息

### 按请求的日志级别

要接收特定请求的日志消息，请在该请求的 `_meta` 中包含
`io.modelcontextprotocol/logLevel`。对于未包含此字段的请求，服务器 **不得**
发送 `notifications/message`。

当该字段存在时，服务器 **可以** 在该请求的响应流上、最终响应之前，发送处于请求级别或更高级别的 `notifications/message`
通知。`notifications/message` 是按请求作用域生效的：服务器 **不得** 在
[`subscriptions/listen`](/specification/draft/basic/patterns/subscriptions)
流上，或在任何其他不同于承载设置日志级别之请求响应的流上发送它。

## 协议消息

### 日志消息通知

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

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "error",
    "logger": "database",
    "data": {
      "error": "连接失败",
      "details": {
        "host": "localhost",
        "port": 5432
      }
    }
  }
}
```

## 错误处理

如果请求的 `_meta` 中携带的 `io.modelcontextprotocol/logLevel` 值不是可识别的 [日志级别](#日志级别)，服务器 **应该** 使用标准 JSON-RPC 错误拒绝该请求：

* 无效日志级别：`-32602`（Invalid params）
* 内部错误：`-32603`（Internal error）

## 实现注意事项

1. 服务器 **应该**：
   * 限制日志消息速率
   * 在数据字段中包含相关上下文
   * 使用一致的记录器名称
   * 移除敏感信息

2. 客户端 **可以**：
   * 在 UI 中展示日志消息
   * 实现日志过滤/搜索
   * 可视化显示严重性
   * 持久化日志消息

## 安全性

1. 日志消息 **不得** 包含：
   * 凭证或秘密
   * 个人身份信息
   * 可能协助攻击的内部系统细节

2. 实现 **应该**：
   * 限制消息速率
   * 验证所有数据字段
   * 控制日志访问
   * 监控敏感内容