生命周期

协议版本:2025-11-25

模型上下文协议 (MCP) 为客户端-服务器连接定义了严格的声明周期,确保适当的功能协商和状态管理。

  1. 初始化:功能协商和协议版本一致
  2. 操作:正常协议通信
  3. 关闭:连接的优雅终止
  sequenceDiagram
    participant Client
    participant Server

    Note over Client,Server: 初始化阶段
    activate Client
    Client->>+Server: 初始化请求
    Server-->>Client: 初始化响应
    Client--)Server: 已初始化通知

    Note over Client,Server: 操作阶段
    rect rgb(200, 220, 250)
        note over Client,Server: 正常协议操作
    end

    Note over Client,Server: 关闭
    Client--)-Server: 断开连接
    deactivate Server
    Note over Client,Server: 连接已关闭

生命周期阶段

初始化

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

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

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

  • 支持的协议版本
  • 客户端功能
  • 客户端实现信息
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {},
      "elicitation": {
        "form": {},
        "url": {}
      },
      "tasks": {
        "requests": {
          "elicitation": {
            "create": {}
          },
          "sampling": {
            "createMessage": {}
          }
        }
      }
    },
    "clientInfo": {
      "name": "ExampleClient",
      "title": "Example Client Display Name",
      "version": "1.0.0",
      "description": "An example MCP client application",
      "icons": [
        {
          "src": "https://example.com/icon.png",
          "mimeType": "image/png",
          "sizes": ["48x48"]
        }
      ],
      "websiteUrl": "https://example.com"
    }
  }
}

服务器必须响应其自己的功能和信息:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "logging": {},
      "prompts": {
        "listChanged": true
      },
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "tools": {
        "listChanged": true
      },
      "tasks": {
        "list": {},
        "cancel": {},
        "requests": {
          "tools": {
            "call": {}
          }
        }
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "title": "Example Server Display Name",
      "version": "1.0.0",
      "description": "An example MCP server providing tools and resources",
      "icons": [
        {
          "src": "https://example.com/server-icon.svg",
          "mimeType": "image/svg+xml",
          "sizes": ["any"]
        }
      ],
      "websiteUrl": "https://example.com/server"
    },
    "instructions": "Optional instructions for the client"
  }
}

成功初始化后,客户端必须发送 initialized 通知以表示它准备好开始正常操作:

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

版本协商

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

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

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

如果使用 HTTP,客户端必须在所有后续请求中向 MCP 服务器包含 MCP-Protocol-Version: <protocol-version> HTTP 头。 有关详细信息,请参阅传输中的协议版本头部分。

功能协商

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

关键功能包括:

类别功能描述
客户端roots提供文件系统 根的能力
客户端sampling支持 LLM 采样 请求
客户端elicitation支持服务器 诱导 请求
客户端tasks支持 任务增强 客户端请求
客户端extensions支持核心协议之外的可选 扩展
客户端experimental描述对非标准实验性功能的支持
服务器prompts提供 提示模板
服务器resources提供可读 资源
服务器tools公开可调用 工具
服务器logging发出结构化 日志消息
服务器completions支持参数 自动完成
服务器tasks支持 任务增强 服务器请求
服务器extensions支持核心协议之外的可选 扩展
服务器experimental描述对非标准实验性功能的支持

功能对象可以描述子功能,例如:

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

扩展协商

客户端和服务器还可以协商对核心协议之外的可选扩展的支持。扩展在功能的 extensions 字段中声明,这是一个从扩展标识符到每个扩展设置对象的映射。

带有扩展的示例客户端功能:

{
  "capabilities": {
    "roots": {},
    "extensions": {
      "io.modelcontextprotocol/apps": {
        "mimeTypes": ["text/html;profile=mcp-app"]
      }
    }
  }
}

带有扩展的示例服务器功能:

{
  "capabilities": {
    "tools": {},
    "extensions": {
      "io.modelcontextprotocol/apps": {}
    }
  }
}

每个扩展指定其设置对象的架构;空对象表示支持但没有其他设置。

如果一方支持扩展而另一方不支持,支持方必须要么回退到核心协议行为,要么使用适当的错误拒绝请求。扩展应该记录其预期的回退行为。

操作

在操作阶段,客户端和服务器根据协商的功能交换消息。

双方应该:

  • 尊重协商的协议版本
  • 仅使用成功协商的功能

关闭

在关闭阶段,一方(通常是客户端)干净地终止协议连接。没有定义特定的关闭消息——相反,应该使用底层传输机制来指示连接终止:

stdio

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

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

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

HTTP

对于 HTTP 传输,关闭通过关闭关联的 HTTP 连接来指示。

超时

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

SDK 和其他中间件应该允许在每个请求的基础上配置这些超时。

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

错误处理

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

  • 协议版本不匹配
  • 未能协商所需的功能
  • 请求 超时

示例初始化错误:

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