Skip to main content
会话代表客户端和代理之间的特定对话或线程。每个会话维护自己的上下文、对话历史记录和状态，允许与同一代理进行多个独立的交互。 在创建会话之前，客户端必须首先完成初始化阶段以建立协议兼容性和功能。

​
创建会话

客户端通过调用 session/new 方法创建新会话，并提供： 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/new",
  "params": {
    "cwd": "/home/user/project",
    "mcpServers": [
      {
        "name": "filesystem",
        "command": "/path/to/mcp-server",
        "args": ["--stdio"],
        "env": []
      }
    ]
  }
}
代理必须用唯一标识此对话的会话 ID 进行响应： 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sessionId": "sess_abc123def456"
  }
}

​
加载会话

支持 loadSession 功能的代理允许客户端恢复之前的对话。此功能支持跨重启持久化以及在不同客户端实例之间共享会话。

​
检查支持

在尝试加载会话之前，客户端必须通过在 initialize 响应中检查 loadSession 字段来验证代理是否支持此功能： 
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "loadSession": true
    }
  }
}
如果 loadSession 为 false 或不存在，则代理不支持加载会话，客户端不得尝试调用 session/load。

​
加载会话

要加载现有会话，客户端必须调用 session/load 方法，并提供： 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/load",
  "params": {
    "sessionId": "sess_789xyz",
    "cwd": "/home/user/project",
    "mcpServers": [
      {
        "name": "filesystem",
        "command": "/path/to/mcp-server",
        "args": ["--mode", "filesystem"],
        "env": []
      }
    ]
  }
}
代理必须以 session/update 通知的形式（如 session/prompt）将整个对话重放到客户端。 例如，来自对话历史记录的用户消息： 
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_789xyz",
    "update": {
      "sessionUpdate": "user_message_chunk",
      "content": {
        "type": "text",
        "text": "What's the capital of France?"
      }
    }
  }
}
后跟代理的响应： 
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_789xyz",
    "update": {
      "sessionUpdate": "agent_message_chunk",
      "content": {
        "type": "text",
        "text": "The capital of France is Paris."
      }
    }
  }
}
当所有对话条目都已流式传输到客户端后，代理必须响应原始的 session/load 请求。 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
然后客户端可以继续发送提示，就像会话从未中断一样。

​
会话 ID

session/new 返回的会话 ID 是会话上下文的唯一标识符。 客户端使用此 ID 来：
  • 通过 session/prompt 发送提示请求
  • 通过 session/cancel 取消正在进行的操作
  • 通过 session/load 加载之前的会话（如果代理支持 loadSession 功能）

​
工作目录

cwd（当前工作目录）参数为会话建立文件系统上下文。此目录：
  • 必须是绝对路径
  • 必须用于会话，无论代理子进程在何处启动
  • 应该作为文件系统上工具操作的边界

​
MCP 服务器

Model Context Protocol (MCP) 允许代理访问外部工具和数据源。创建会话时，客户端可以包含代理应连接的 MCP 服务器的连接详细信息。 MCP 服务器可以使用不同的传输方式连接。所有代理必须支持 stdio 传输，而 HTTP 和 SSE 传输是可选功能，可以在初始化期间检查。 虽然规范不要求，但新代理应该支持 HTTP 传输，以确保与现代 MCP 服务器的兼容性。

​
传输类型

​
Stdio 传输

所有代理必须支持通过 stdio（标准输入/输出）连接到 MCP 服务器。这是默认的传输机制。
​
name
string
required
服务器的人类可读标识符
​
command
string
required
MCP 服务器可执行文件的绝对路径
​
args
array
required
传递给服务器的命令行参数
​
env
EnvVariable[]
启动服务器时要设置的环境变量
Stdio 传输配置示例： 
{
  "name": "filesystem",
  "command": "/path/to/mcp-server",
  "args": ["--stdio"],
  "env": [
    {
      "name": "API_KEY",
      "value": "secret123"
    }
  ]
}

​
HTTP 传输

当代理支持 mcpCapabilities.http 时，客户端可以使用 HTTP 传输指定 MCP 服务器配置。
​
type
string
required
必须是 "http" 以指示 HTTP 传输
​
name
string
required
服务器的人类可读标识符
​
url
string
required
MCP 服务器的 URL
​
headers
HttpHeader[]
required
发送到服务器的请求中包含的 HTTP 头
HTTP 传输配置示例： 
{
  "type": "http",
  "name": "api-server",
  "url": "https://api.example.com/mcp",
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer token123"
    },
    {
      "name": "Content-Type",
      "value": "application/json"
    }
  ]
}

​
SSE 传输

当代理支持 mcpCapabilities.sse 时，客户端可以使用 SSE 传输指定 MCP 服务器配置。
此传输已被 MCP 规范弃用。
​
type
string
required
必须是 "sse" 以指示 SSE 传输
​
name
string
required
服务器的人类可读标识符
​
url
string
required
SSE 端点的 URL
​
headers
HttpHeader[]
required
建立 SSE 连接时包含的 HTTP 头
SSE 传输配置示例： 
{
  "type": "sse",
  "name": "event-stream",
  "url": "https://events.example.com/mcp",
  "headers": [
    {
      "name": "X-API-Key",
      "value": "apikey456"
    }
  ]
}

​
检查传输支持

在使用 HTTP 或 SSE 传输之前，客户端必须在初始化期间验证代理的功能： 
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "mcpCapabilities": {
        "http": true,
        "sse": true
      }
    }
  }
}
如果 mcpCapabilities.http 为 false 或不存在，则代理不支持 HTTP 传输。 如果 mcpCapabilities.sse 为 false 或不存在，则代理不支持 SSE 传输。 代理应该连接到客户端指定的所有 MCP 服务器。 客户端可以使用此能力通过包含自己的 MCP 服务器直接向底层语言模型提供工具。