鸭梨公共文档

主题

生命周期 ​

协议修订版本：2025-06-18

Model Context Protocol (MCP) 为客户端-服务器连接定义了严格的生命周期，确保正确的能力协商和状态管理。

  1. 初始化：能力协商和协议版本协商
  2. 运行：正常的协议通信
  3. 关闭：优雅地终止连接

1. 生命周期阶段 ​

1.1 初始化 ​

初始化阶段必须是客户端和服务器之间的第一次交互。在此阶段，客户端和服务器：

  • 建立协议版本兼容性
  • 交换和协商能力
  • 共享实现详细信息

客户端必须通过发送包含以下内容的 initialize 请求来启动此阶段：

  • 支持的协议版本
  • 客户端能力
  • 客户端实现信息
json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {},
      "elicitation": {}
    },
    "clientInfo": {
      "name": "ExampleClient",
      "title": "Example Client Display Name",
      "version": "1.0.0"
    }
  }
}

服务器必须响应其自己的能力和信息：

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "logging": {},
      "prompts": {
        "listChanged": true
      },
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "title": "Example Server Display Name",
      "version": "1.0.0"
    },
    "instructions": "Optional instructions for the client"
  }
}

成功初始化后，客户端必须发送 initialized 通知以表明它已准备好开始正常操作：

json
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}
  • 客户端不应在服务器响应 initialize 请求之前发送除 ping 之外的请求。
  • 服务器不应在接收到 initialized 通知之前发送除 ping 和 logging 之外的请求。

1.1.1 版本协商 ​

在 initialize 请求中，客户端必须发送它支持的协议版本。这应该是客户端支持的最新版本。

如果服务器支持请求的协议版本，它必须响应相同的版本。否则，服务器必须响应它支持的另一个协议版本。这应该是服务器支持的最新版本。

如果客户端不支持服务器响应中的版本，它应该断开连接。

NOTE

如果使用 HTTP，客户端必须在所有后续向 MCP 服务器的请求中包含 MCP-Protocol-Version: <protocol-version> HTTP 头。

有关详细信息，请参阅 传输中的协议版本头部分。

1.1.2 能力协商 ​

客户端和服务器能力确定会话期间可用的可选协议功能。

主要能力包括：

类别能力描述
客户端roots提供文件系统 根目录 的能力
客户端sampling支持 LLM 采样 请求
客户端elicitation支持服务器 启发 请求
客户端experimental描述对非标准实验性功能的支持
服务器prompts提供 提示模板
服务器resources提供可读 资源
服务器tools公开可调用 工具
服务器logging发出结构化 日志消息
服务器completions支持参数 自动完成
服务器experimental描述对非标准实验性功能的支持

能力对象可以描述子能力，如：

  • listChanged：支持列表更改通知（用于提示、资源和工具）
  • subscribe：支持订阅单个项目的更改（仅限资源）

1.2 运行 ​

在运行阶段，客户端和服务器根据协商的能力交换消息。

双方必须：

  • 遵守协商的协议版本
  • 仅使用成功协商的能力

1.3 关闭 ​

在关闭阶段，一方（通常是客户端）干净地终止协议连接。未定义特定的关闭消息——而是应使用底层传输机制来信号连接终止：

1.3.1 stdio ​

对于 stdio 传输，客户端应该通过以下方式启动关闭：

  1. 首先，关闭到子进程（服务器）的输入流
  2. 等待服务器退出，或者如果服务器在合理时间内未退出则发送 SIGTERM
  3. 如果服务器在发送 SIGTERM 后的合理时间内仍未退出，则发送 SIGKILL

服务器可以通过关闭其到客户端的输出流并退出来启动关闭。

1.3.2 HTTP ​

对于 HTTP 传输，关闭通过关闭相关的 HTTP 连接来表示。

2. 超时 ​

实现应该为所有发送的请求建立超时，以防止连接挂起和资源耗尽。当请求在超时期间内未收到成功或错误响应时，发送方应该为该请求发出 取消通知 并停止等待响应。

SDK 和其他中间件应该允许根据每个请求配置这些超时。

当接收到与请求对应的 进度通知 时，实现可以选择重置超时时钟，因为这表明实际上正在进行工作。但是，实现应该始终强制执行最大超时，无论进度通知如何，以限制行为异常的客户端或服务器的影响。

3. 错误处理 ​

实现应该准备好处理这些错误情况：

  • 协议版本不匹配
  • 无法协商所需能力
  • 请求 超时

初始化错误示例：

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Unsupported protocol version",
    "data": {
      "supported": ["2024-11-05"],
      "requested": "1.0.0"
    }
  }
}