session/new may fail with an auth_required error until the Client completes the authentication flow.
Creating a session
Clients create a new session by calling thesession/new method with:
- The working directory for the session
- A list of MCP servers the Agent should connect to
Loading sessions
Agents that support theloadSession 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 theloadSession field in the initialize response:
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 thesession/load method with:
- The Session ID to resume
- MCP servers to connect to
- The working directory
session/update notifications (like session/prompt).
Session compactions are
replayed using the same update, chunk, and patch semantics as live delivery.
The Client’s session.compaction capability is required for replay as well as
live delivery.
Live-only notices are not
conversation history and SHOULD NOT be replayed. If the underlying
condition is still relevant after loading finishes, the Agent may emit a new
notice as a new live event, subject to the Client’s session.notices
capability.
Prompt suggestions are not conversation history and SHOULD NOT be replayed. A loaded session starts with an empty list of suggestions. After loading finishes, the Agent may send a new prompt_suggestions_update, subject to the Client’s session.promptSuggestions capability.
Unstable session cursors are part of the replayed history, subject to the Client’s session.cursors capability:
- The Agent SHOULD send a
cursor_updatefor each cursor in the loaded history that it still accepts. A replayed update carries the cursor’scapabilitiesandanchor, like a first update, and follows the replayed entity it is anchored to. - Agents SHOULD use the same
cursorIdfor the same position in every load. - A load rebuilds the session’s cursors. The Client SHOULD discard the cursors it held for the session and build them again from the replayed
cursor_updatenotifications. - Message IDs need not stay the same across a load, so the Client does not match a replayed anchor to an entity it held before.
messageId is an opaque, unique identifier for the replayed message.
When all the conversation entries have been streamed to the Client, the
Agent MUST respond to the original session/load request.
Resuming sessions
Agents that advertisesessionCapabilities.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 thesessionCapabilities.resume field
in the initialize response:
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 thesession/resume method with:
- The Session ID to resume
- MCP servers to connect to
- The working directory
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.
Closing active sessions
Agents that advertisesessionCapabilities.close allow Clients to tell the
Agent to cancel any ongoing work for a session and free any resources
associated with that active session.
Checking support
Before attempting to close a session, Clients MUST verify that the Agent supports this capability by checking thesessionCapabilities.close field in
the initialize response:
sessionCapabilities.close is not present, the Agent does not support
closing sessions and Clients MUST NOT attempt to call session/close.
Closing a session
To close an active session, Clients MUST call thesession/close method
with the session ID:
session/cancel had been called, then free the
resources associated with the session.
On success, the Agent responds with an empty result object:
-32002 response to
session/close as a successful close. See Unknown Sessions.
Additional workspace roots
Agents that advertisesessionCapabilities.additionalDirectories allow Clients
to include additionalDirectories on supported session lifecycle requests to
expand the session’s effective filesystem root set. Supported stable lifecycle
requests include session/new, session/load, and session/resume.
additionalDirectories has the following behavior:
cwdremains the primary working directory and the base for relative paths- each
additionalDirectoriesentry MUST be an absolute path - omitting the field or providing an empty array activates no additional roots for the resulting session
- on
session/loadandsession/resume, Clients must send the full intended additional-root list again. That list may differ from any previous or reported list as long as the requestcwdmatches the session’scwd, and omitting the field or providing an empty array does not restore stored roots implicitly
additionalDirectories when the Agent advertises sessionCapabilities.additionalDirectories.
System prompt
Agents that advertisesessionCapabilities.systemPrompt allow Clients to include
system-level instructions on session/new, session/load, session/resume,
and, when the Agent supports it, session/fork.
systemPrompt has the following behavior:
modeis required and selects how the Agent combinescontentwith its own instructionsmodevalues beginning with_are reserved for implementation-specific modes, and other unknown values for future ACP modes. Clients MUST only use a mode the Agent advertised. An Agent that receives a mode it does not support MUST return an error rather than treating it asappendoroverrideappendaddscontentto the Agent’s own instructions rather than replacing them. The Agent SHOULD give it system-level precedence, for example in the model’s system prompt or developer instructions rather than in user-turn content. Where it is placed and how it is formatted is up to the Agentoverridereplaces the Agent’s built-in default instructions. It does not change tool availability, MCP servers, permissions, or session configuration. Context the Agent supplies from the workspace or environment, such asAGENTS.mdfiles or skill listings, MAY still be included, and Agents SHOULD document what they keep. Clients that useoverridetake responsibility for any tool guidance or safety instructions the Agent’s default instructions provided- only
textcontent blocks are supported for now: Agents MUST accept them, and Clients MUST NOT send other content block types until a future capability allows them - Clients MUST NOT send an empty
contentarray. Agents MAY reject one with-32602without creating, loading, resuming, or forking the session - omitting the field or setting it to
nullonsession/newmeans the Agent uses its default instructions - on
session/load,session/resume, andsession/fork, Clients SHOULD send the samesystemPromptthey used when the session was created. When it is omitted, the Agent may keep a prompt it stored with the session or use its default. When it differs, the Agent SHOULD apply it, and MAY defer the change until it next rebuilds its prompt (for example, after compaction) when applying it immediately would discard prompt caches or preserved reasoning - if the Agent cannot apply a supplied
systemPrompt, for example because of an unadvertised mode, an unsupported content block type, or content that exceeds its limits, it MUST return an error and MUST NOT create, load, resume, or fork the session. JSON-RPC-32602(Invalid params) is the RECOMMENDED error for malformed or unsupported values
systemPrompt when the Agent advertises sessionCapabilities.systemPrompt, and MUST only use override mode when the Agent also advertises sessionCapabilities.systemPrompt.mode.override:
Initial config option values (unstable)
Agents that advertisesessionCapabilities.options accept a configOptions list on session/new, session/load, session/resume, and, when supported, session/fork. The Agent applies the entries in order, as if the Client had called session/set_config_option for each one after setup, and returns the resulting values in the response. Clients can get the options and allowed values before setup with session/options. See Options before a session exists.
Session ID
The session ID returned bysession/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 theloadSessioncapability) - Resume previous sessions via
session/resume(if the Agent supports thesessionCapabilities.resumecapability) - Close active sessions via
session/close(if the Agent supports thesessionCapabilities.closecapability)
Working directory
Thecwd (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
sessionCapabilities.additionalDirectories is in use, the session’s effective root set is [cwd, ...additionalDirectories]. This root set SHOULD serve as a boundary for tool operations on the file system.
Workspace root security
The root set declares the session’s scope. It confines shell commands only when a sandbox enforces it.- Clients SHOULD only include directories the user expects the Agent to access, such as the workspace or directories the Client provides, like skills.
- Agents SHOULD NOT treat model output, Agent content, or replayed history as granting access outside the root set. Access outside it goes through a permission request.
- Implementations that enforce the root set SHOULD check the resolved path at the time of use, compare paths by component, and fail closed.
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. Example stdio transport configuration:HTTP transport
When the Agent supportsmcpCapabilities.http, Clients can specify MCP servers configurations using the HTTP transport.
Example HTTP transport configuration:
SSE transport
When the Agent supportsmcpCapabilities.sse, Clients can specify MCP servers configurations using the SSE transport.
Example SSE transport configuration:
Checking transport support
Before using HTTP or SSE transports, Clients MUST verify the Agent’s capabilities during initialization: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.
Security
MCP server configurations can launch processes, and theirenv and headers values are credentials.
- Agents SHOULD launch
commandwithargsas separate arguments, without a shell. - Clients SHOULD NOT send a stdio server from workspace files or Agent output until the user has approved its exact command, arguments, and environment variable names.
- Agents SHOULD NOT include
envorheadersvalues in session updates, errors,_meta,session/listresults, replayed history, model context, or command lines, and SHOULD NOT log or persist them. - Agents SHOULD send
headersonly to the configured origin. - Clients that persist
mcpServersSHOULD keep credentials in operating-system secret storage and SHOULD NOT log them.