Skip to main content
The Initialization phase allows Clients and Agents to negotiate protocol versions, capabilities, and authentication methods.

Before a Session can be created, Clients MUST initialize the connection by calling the initialize method with: They SHOULD also provide a name and version to the Agent.
The Agent MUST respond with the chosen protocol version and the capabilities it supports. It SHOULD also provide a name and version to the Client as well:

Protocol version

The protocol versions that appear in the initialize requests and responses are a single integer that identifies a MAJOR protocol version. This version is only incremented when breaking changes are introduced. Clients and Agents MUST agree on a protocol version and act according to its specification. See Capabilities to learn how non-breaking features are introduced.

Version negotiation

The initialize request MUST include the latest protocol version the Client supports. If the Agent supports the requested version, it MUST respond with the same version. Otherwise, the Agent MUST respond with the latest version it supports. If the Client does not support the version specified by the Agent in the initialize response, the Client SHOULD close the connection and inform the user about it.

Capabilities

Capabilities describe features supported by the Client and the Agent. All capabilities included in the initialize request are OPTIONAL. Clients and Agents SHOULD support all possible combinations of their peer’s capabilities. The introduction of new capabilities is not considered a breaking change. Therefore, Clients and Agents MUST treat all capabilities omitted in the initialize request as UNSUPPORTED. Capabilities are high-level and are not attached to a specific base protocol concept. Capabilities may specify the availability of protocol methods, notifications, or a subset of their parameters. They may also signal behaviors of the Agent or Client implementation. Implementations can also advertise custom capabilities using the _meta field to indicate support for protocol extensions.

Client capabilities

The Client SHOULD specify whether it supports the following capabilities:

Terminal authentication

boolean
The Client can reproduce the configured Agent invocation in an interactive terminal. When true, the Agent may advertise type: "terminal" authentication methods.
Learn more about Terminal Authentication

File system

boolean
The fs/read_text_file method is available.
boolean
The fs/write_text_file method is available.
Learn more about File System methods

Terminal

boolean
All terminal/* methods are available, allowing the Agent to execute and manage shell commands.
Learn more about Terminals

Elicitation

ElicitationCapabilities Object
The Client advertises its supported elicitation/create modes. Omitted or null means no modes are advertised. A present object advertises each mode only through its corresponding non-null form or url field. Empty and all-null objects are valid but advertise no supported modes. Unlike MCP, ACP does not treat {} as form support.
Learn more about Elicitation

Plan operations

PlanCapabilities Object
The Client can receive plan_update and plan_removed session updates. Omitted or null means the Client does not advertise support, and the Agent sends plans with the plan update instead. Supplying {} means the Client can receive both update types.
Learn more about Plan operations

Boolean config options

BooleanConfigOptionCapabilities Object
The Client supports boolean session configuration options. Omitted or null at any level means the Client does not advertise support. Supplying {} means Agents may include type: "boolean" options in v1 configOptions payloads.
Learn more about Session Config Options

Session compaction

CompactionCapabilities Object
The Client supports ID-addressed compaction_update and compaction_summary_chunk session updates, including their lifecycle, placement, patch, and replay semantics. Omitted or null at either level means unsupported. Supplying {} advertises the complete contract. Agents must not send these updates to a v1 Client that does not advertise it.
Learn more about Session Compaction

Session notices

NoticeCapabilities Object
The Client can present live notice session updates to the user. This field is optional and nullable. Omitting session or notices, or setting either to null, means unsupported. Supplying {} advertises notice support. Agents must not send notices without this capability and may instead use an agent message when the information should still be surfaced to the user.
Learn more about Session Notices

Prompt suggestions (unstable)

PromptSuggestionsCapabilities Object
The Client can offer the suggestions in prompt_suggestions_update session updates to the user. This field is optional and nullable. Omitting session or promptSuggestions, or setting either to null, means unsupported. Supplying {} means the Client can offer suggestions made of text and resource_link content blocks. Agents must not send prompt_suggestions_update without this capability.
The Client opts in to other content types with the following fields. They have the same names as the Agent’s prompt capabilities, but each one is an object. Omitted or null means unsupported. Supplying {} means supported.
PromptSuggestionsImageCapabilities Object
Suggestions may include image content blocks.
PromptSuggestionsAudioCapabilities Object
Suggestions may include audio content blocks.
PromptSuggestionsEmbeddedContextCapabilities Object
Suggestions may include resource content blocks.
Learn more about Prompt Suggestions

Session cursors (unstable)

SessionCursorsCapabilities Object
The Client handles cursor_update session updates. This field is optional and nullable. Omitting session or cursors, or setting either to null, means unsupported. Supplying {} means supported. Agents must not send cursor_update without this capability.
Learn more about Session Cursors

Subagents (unstable)

SubagentCapabilities Object
The Client handles subagent_update, session_message, and session_message_chunk session updates, and applies the restrictions on what it sends for a child session. This field is optional and nullable. Omitted or null means unsupported. Supplying {} means supported. Agents must not send these updates without this capability.
Learn more about Subagents

Agent capabilities

The Agent SHOULD specify whether it supports the following capabilities:
boolean
default: false
The session/load method is available.
PromptCapabilities Object
Object indicating the different types of content that may be included in session/prompt requests.
AgentAuthCapabilities Object
Authentication-related capabilities supported by the Agent.

Prompt capabilities

As a baseline, all Agents MUST support text and resource_link content blocks in session/prompt requests. Optionally, they MAY support richer types of content by specifying the following capabilities:
boolean
default: false
The prompt may include image content blocks
boolean
default: false
The prompt may include audio content blocks
boolean
default: false
The prompt may include resource content blocks

MCP capabilities

boolean
default: false
The Agent supports connecting to MCP servers over HTTP.
boolean
default: false
The Agent supports connecting to MCP servers over SSE.Note: This transport has been deprecated by the MCP spec.

Authentication capabilities

LogoutCapabilities Object
The logout method is available.
AuthStatusCapabilities Object
Unstable. The auth/status method and the auth/status_update notification are available. Omitted or null both mean the Agent does not advertise support. Supplying an empty object means the Agent supports them.
Learn more about Authentication

Session capabilities

As a baseline, all Agents MUST support session/new, session/prompt, session/cancel, and session/update. Optionally, they MAY support other session methods and notifications by specifying additional capabilities.
SessionDeleteCapabilities Object
The session/delete method is available. Omitted or null both mean the Agent does not advertise support. Supplying an empty object means the Agent supports deleting sessions from session/list.
SessionArchiveCapabilities Object
Unstable. The session/archive and session/unarchive methods, the archived filter on session/list, and archived on listed sessions are available. Omitted or null both mean the Agent does not advertise support. Supplying an empty object means the Agent supports them. See Archived Sessions.
SessionAdditionalDirectoriesCapabilities Object
The Agent supports additionalDirectories on supported session lifecycle requests. Omitted or null both mean the Agent does not advertise support. Supplying {} means the Agent supports additional workspace roots.
SessionSystemPromptCapabilities Object
The Agent supports systemPrompt on session lifecycle requests. Omitted or null both mean the Agent does not advertise support. Supplying {} means the Agent supports append mode. Supplying { "mode": { "override": {} } } also advertises override mode.
SessionOptionsCapabilities Object
Unstable. The session/options method and configOptions on session setup requests are available. Omitted or null both mean the Agent does not advertise support. Supplying an empty object means the Agent supports both.
SessionStatusCapabilities Object
Unstable. The session/status method is available. Omitted or null both mean the Agent does not advertise support. Supplying an empty object means the Agent supports checking session status.
SessionTitleCapabilities Object
Unstable. The session/set_title method is available. Omitted or null both mean the Agent does not advertise support. Supplying an empty object means Clients can set session titles. Agents report titles through session/list and session_info_update without this capability.
session/load is still handled by the top-level load_session capability. This will be unified in future versions of the protocol.

Implementation information

Both Clients and Agents SHOULD provide information about their implementation in the clientInfo and agentInfo fields respectively. Both take the following three fields:
string
required
Intended for programmatic or logical use, but can be used as a display name fallback if title isn’t present.
string
Intended for UI and end-user contexts and optimized to be human-readable and easily understood. Optional. Omitted and null are equivalent. If not provided, the name should be used for display.
string
required
Version of the implementation. Can be displayed to the user or used for debugging or metrics purposes.
Note: in future versions of the protocol, this information will be required.

Once the connection is initialized, you’re ready to create a session and begin the conversation with the Agent.