agent-client-protocol/docs/protocol/draft/session-setup.mdx at 36e5d2f7913a0bf998d8e8d62dc8535aeaa3f598 · agentclientprotocol/agent-client-protocol

title	Session Setup
description	Creating and loading sessions

Sessions represent a specific conversation or thread between the Client and Agent. Each session maintains its own context, conversation history, and state, allowing multiple independent interactions with the same Agent.

Before creating a session, Clients MUST first complete the initialization phase to establish protocol compatibility and capabilities.

sequenceDiagram
    participant Client
    participant Agent

    Note over Agent,Client: Initialized

    alt
        Client->>Agent: session/new
        Note over Agent: Create session context
        Note over Agent: Connect to MCP servers
        Agent-->>Client: session/new response (sessionId)
    else
        Client->>Agent: session/load (sessionId)
        Note over Agent: Restore session context
        Note over Agent: Connect to MCP servers
        Note over Agent,Client: Replay conversation history...
        Agent->>Client: session/update
        Agent->>Client: session/update
        Note over Agent,Client: All content streamed
        Agent-->>Client: session/load response
    else
        Client->>Agent: session/resume (sessionId)
        Note over Agent: Restore session context
        Note over Agent: Connect to MCP servers
        Agent-->>Client: session/resume response
    end

    Note over Client,Agent: Ready for prompts

Creating a Session

Clients create a new session by calling the session/new method with:

The working directory for the session
A list of MCP servers the Agent should connect to

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/new",
  "params": {
    "cwd": "/home/user/project",
    "mcpServers": [
      {
        "name": "filesystem",
        "command": "/path/to/mcp-server",
        "args": ["--stdio"],
        "env": []
      }
    ]
  }
}

The Agent MUST respond with a unique Session ID that identifies this conversation:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sessionId": "sess_abc123def456"
  }
}

Loading Sessions

Agents that support the loadSession capability allow Clients to resume previous conversations with history replay. This feature enables persistence across restarts and sharing sessions between different Client instances.

Checking Support

Before attempting to load a session, Clients MUST verify that the Agent supports this capability by checking the loadSession field in the initialize response:

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "loadSession": true
    }
  }
}

If loadSession is false or not present, the Agent does not support loading sessions and Clients MUST NOT attempt to call session/load.

Loading a Session

To load an existing session, Clients MUST call the session/load method with:

The Session ID to resume
MCP servers to connect to
The working directory

{
  "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": []
      }
    ]
  }
}

The Agent MUST replay the entire conversation to the Client in the form of session/update notifications (like session/prompt).

For example, a user message from the conversation history:

{
  "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?"
      }
    }
  }
}

Followed by the agent's response:

{
  "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."
      }
    }
  }
}

When all the conversation entries have been streamed to the Client, the Agent MUST respond to the original session/load request.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}

The response MAY also include initial mode, model, or session configuration state when those features are supported by the Agent.

The Client can then continue sending prompts as if the session was never interrupted.

Resuming Sessions

This section describes the preview `session/resume` method. Clients MUST gate usage on the `sessionCapabilities.resume` capability being present during initialization.

Agents that advertise sessionCapabilities.resume allow Clients to reconnect to an existing session without replaying the conversation history.

Checking Support

Before attempting to resume a session, Clients MUST verify that the Agent supports this capability by checking for the sessionCapabilities.resume field in the initialize response:

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "resume": {}
      }
    }
  }
}

If sessionCapabilities.resume is not present, the Agent does not support resuming sessions and Clients MUST NOT attempt to call session/resume.

Resuming a Session

To resume an existing session without replaying prior messages, Clients MUST call the session/resume method with:

The Session ID to resume
MCP servers to connect to
The working directory

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/resume",
  "params": {
    "sessionId": "sess_789xyz",
    "cwd": "/home/user/project",
    "mcpServers": [
      {
        "name": "filesystem",
        "command": "/path/to/mcp-server",
        "args": ["--mode", "filesystem"],
        "env": []
      }
    ]
  }
}

Unlike session/load, the Agent MUST NOT replay the conversation history via session/update notifications before responding. Instead, it restores the session context, reconnects to the requested MCP servers, and returns once the session is ready to continue.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {}
}

The response MAY also include initial mode, model, or session configuration state when those features are supported by the Agent.

Additional Workspace Roots

This section describes the unstable `sessionCapabilities.additionalDirectories` capability. Clients MUST gate usage on that capability being present during initialization.

When advertised, Clients MAY include additionalDirectories on supported session lifecycle requests to expand the session's effective filesystem root set. In the stable lifecycle pages, that means session/new and session/load. The same unstable field is also available on session/resume and session/fork when those methods are supported.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/load",
  "params": {
    "sessionId": "sess_789xyz",
    "cwd": "/home/user/project",
    "additionalDirectories": [
      "/home/user/shared-lib",
      "/home/user/product-docs"
    ],
    "mcpServers": []
  }
}

When present, additionalDirectories has the following behavior:

cwd remains the primary working directory and the base for relative paths
each additionalDirectories entry MUST be an absolute path
omitting the field or providing an empty array activates no additional roots for the resulting session
on session/load and session/resume, Clients must send the full intended additional-root list again because omitting the field or providing an empty array does not restore stored roots implicitly

Session ID

The session ID returned by session/new is a unique identifier for the conversation context.

Clients use this ID to:

Send prompt requests via session/prompt
Cancel ongoing operations via session/cancel
Load previous sessions via session/load (if the Agent supports the loadSession capability)
Resume previous sessions via session/resume (if the Agent supports the preview sessionCapabilities.resume capability)

Working Directory

The cwd (current working directory) parameter establishes the primary file system context for the session. This directory:

MUST be an absolute path
MUST be used for the session regardless of where the Agent subprocess was spawned
MUST remain the base for relative-path resolution
MUST be part of the session's effective root set

When the unstable sessionCapabilities.additionalDirectories capability is in use, the session's effective root set is [cwd, ...additionalDirectories]. Otherwise, the effective root set is just cwd.

MCP Servers

The Model Context Protocol (MCP) allows Agents to access external tools and data sources. When creating a session, Clients MAY include connection details for MCP servers that the Agent should connect to.

MCP servers can be connected to using different transports. All Agents MUST support the stdio transport, while HTTP and SSE transports are optional capabilities that can be checked during initialization.

While they are not required to by the spec, new Agents SHOULD support the HTTP transport to ensure compatibility with modern MCP servers.

Transport Types

Stdio Transport

All Agents MUST support connecting to MCP servers via stdio (standard input/output). This is the default transport mechanism.

A human-readable identifier for the server The absolute path to the MCP server executable Command-line arguments to pass to the server Environment variables to set when launching the server The name of the environment variable. The value of the environment variable.

Example stdio transport configuration:

{
  "name": "filesystem",
  "command": "/path/to/mcp-server",
  "args": ["--stdio"],
  "env": [
    {
      "name": "API_KEY",
      "value": "secret123"
    }
  ]
}

HTTP Transport

When the Agent supports mcpCapabilities.http, Clients can specify MCP servers configurations using the HTTP transport.

Must be `"http"` to indicate HTTP transport A human-readable identifier for the server The URL of the MCP server HTTP headers to include in requests to the server The name of the HTTP header. The value to set for the HTTP header.

Example HTTP transport configuration:

{
  "type": "http",
  "name": "api-server",
  "url": "https://api.example.com/mcp",
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer token123"
    },
    {
      "name": "Content-Type",
      "value": "application/json"
    }
  ]
}

SSE Transport

When the Agent supports mcpCapabilities.sse, Clients can specify MCP servers configurations using the SSE transport.

This transport was deprecated by the MCP spec.

Must be `"sse"` to indicate SSE transport A human-readable identifier for the server The URL of the SSE endpoint HTTP headers to include when establishing the SSE connection The name of the HTTP header. The value to set for the HTTP header.

Example SSE transport configuration:

{
  "type": "sse",
  "name": "event-stream",
  "url": "https://events.example.com/mcp",
  "headers": [
    {
      "name": "X-API-Key",
      "value": "apikey456"
    }
  ]
}

Checking Transport Support

Before using HTTP or SSE transports, Clients MUST verify the Agent's capabilities during initialization:

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "mcpCapabilities": {
        "http": true,
        "sse": true
      }
    }
  }
}

If mcpCapabilities.http is false or not present, the Agent does not support HTTP transport. If mcpCapabilities.sse is false or not present, the Agent does not support SSE transport.

Agents SHOULD connect to all MCP servers specified by the Client.

Clients MAY use this ability to provide tools directly to the underlying language model by including their own MCP server.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Creating a Session

Loading Sessions

Checking Support

Loading a Session

Resuming Sessions

Checking Support

Resuming a Session

Additional Workspace Roots

Session ID

Working Directory

MCP Servers

Transport Types

Stdio Transport

HTTP Transport

SSE Transport

Checking Transport Support

FilesExpand file tree

session-setup.mdx

Latest commit

History

session-setup.mdx

File metadata and controls

Creating a Session

Loading Sessions

Checking Support

Loading a Session

Resuming Sessions

Checking Support

Resuming a Session

Additional Workspace Roots

Session ID

Working Directory

MCP Servers

Transport Types

Stdio Transport

HTTP Transport

SSE Transport

Checking Transport Support