schema.mdx

title	Schema
description	Schema definitions for the Agent Client Protocol

Agent

Defines the interface that all ACP-compliant agents must implement.

Agents are programs that use generative AI to autonomously modify code. They handle requests from clients and execute tasks using language models and tools.

authenticate

Authenticates the client using the specified authentication method.

Called when the agent requires authentication before allowing session creation. The client provides the authentication method ID that was advertised during initialization.

After successful authentication, the client can proceed to create sessions with new_session without receiving an auth_required error.

See protocol docs: Initialization

AuthenticateRequest

Request parameters for the authenticate method.

Specifies which authentication method to use.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="methodId" type={AuthMethodId} required

The ID of the authentication method to use. Must be one of the methods advertised in the initialize response.

AuthenticateResponse

Response to authenticate method

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations

initialize

Establishes the connection with a client and negotiates protocol capabilities.

This method is called once at the beginning of the connection to:

• Negotiate the protocol version to use
• Exchange capability information between client and agent
• Determine available authentication methods

The agent should respond with its supported protocol version and capabilities.

See protocol docs: Initialization

InitializeRequest

Request parameters for the initialize method.

Sent by the client to establish connection and negotiate capabilities.

See protocol docs: Initialization

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="clientCapabilities" type={ClientCapabilities} > Capabilities supported by the client.

- Default: `{"fs":{"readTextFile":false,"writeTextFile":false},"terminal":false}`

ProtocolVersion} required> The latest protocol version supported by the client.

InitializeResponse

Response from the initialize method.

Contains the negotiated protocol version and agent capabilities.

See protocol docs: Initialization

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="agentCapabilities" type={AgentCapabilities} > Capabilities supported by the agent.

- Default: `{"loadSession":false,"mcpCapabilities":{"http":false,"sse":false},"promptCapabilities":{"audio":false,"embeddedContext":false,"image":false}}`

AuthMethod[]} > Authentication methods supported by the agent.

- Default: `[]`

ProtocolVersion} required> The protocol version the client specified if supported by the agent, or the latest protocol version supported by the agent.

The client should disconnect, if it doesn't support this version.

session/cancel

Cancels ongoing operations for a session.

This is a notification sent by the client to cancel an ongoing prompt turn.

Upon receiving this notification, the Agent SHOULD:

• Stop all language model requests as soon as possible
• Abort all tool call invocations in progress
• Send any pending session/update notifications
• Respond to the original session/prompt request with StopReason::Cancelled

See protocol docs: Cancellation

CancelNotification

Notification to cancel ongoing operations for a session.

See protocol docs: Cancellation

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="sessionId" type={SessionId} required

The ID of the session to cancel operations for.

session/load

Loads an existing session to resume a previous conversation.

This method is only available if the agent advertises the loadSession capability.

The agent should:

• Restore the session context and conversation history
• Connect to the specified MCP servers
• Stream the entire conversation history back to the client via notifications

See protocol docs: Loading Sessions

LoadSessionRequest

Request parameters for loading an existing session.

Only available if the Agent supports the loadSession capability.

See protocol docs: Loading Sessions

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="cwd" type={"string"} required> The working directory for this session. <ResponseField name="mcpServers" type={ <> McpServer [] </> } required

List of MCP servers to connect to for this session. <ResponseField name="sessionId" type={SessionId} required

The ID of the session to load.

LoadSessionResponse

Response from loading an existing session.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="modes" type={<>SessionModeState | null</>} > Initial mode state if supported by the Agent

See protocol docs: Session Modes

session/new

Creates a new conversation session with the agent.

Sessions represent independent conversation contexts with their own history and state.

The agent should:

• Create a new session context
• Connect to any specified MCP servers
• Return a unique session ID for future requests

May return an auth_required error if the agent requires authentication.

See protocol docs: Session Setup

NewSessionRequest

Request parameters for creating a new session.

See protocol docs: Creating a Session

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="cwd" type={"string"} required> The working directory for this session. Must be an absolute path. <ResponseField name="mcpServers" type={ <> McpServer [] </> } required

List of MCP (Model Context Protocol) servers the agent should connect to.

NewSessionResponse

Response from creating a new session.

See protocol docs: Creating a Session

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="modes" type={<>SessionModeState | null</>} > Initial mode state if supported by the Agent

See protocol docs: Session Modes

SessionId} required> Unique identifier for the created session.

Used in all subsequent requests for this conversation.

session/prompt

Processes a user prompt within a session.

This method handles the whole lifecycle of a prompt:

• Receives user messages with optional context (files, images, etc.)
• Processes the prompt using language models
• Reports language model content and tool calls to the Clients
• Requests permission to run tools
• Executes any requested tool calls
• Returns when the turn is complete with a stop reason

See protocol docs: Prompt Turn

PromptRequest

Request parameters for sending a user prompt to the agent.

Contains the user's message and any additional context.

See protocol docs: User Message

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="prompt" type={<>ContentBlock[]</>} required> The blocks of content that compose the user's message.

As a baseline, the Agent MUST support ContentBlock::Text and ContentBlock::ResourceLink, while other variants are optionally enabled via PromptCapabilities.

The Client MUST adapt its interface according to PromptCapabilities.

The client MAY include referenced pieces of context as either ContentBlock::Resource or ContentBlock::ResourceLink.

When available, ContentBlock::Resource is preferred as it avoids extra round-trips and allows the message to include pieces of context from sources the agent may not have access to.

SessionId} required> The ID of the session to send this user message to

PromptResponse

Response from processing a user prompt.

See protocol docs: Check for Completion

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="stopReason" type={StopReason} required

Indicates why the agent stopped processing the turn.

session/set_mode

Sets the current mode for a session.

Allows switching between different agent modes (e.g., "ask", "architect", "code") that affect system prompts, tool availability, and permission behaviors.

The mode must be one of the modes advertised in availableModes during session creation or loading. Agents may also change modes autonomously and notify the client via current_mode_update notifications.

This method can be called at any time during a session, whether the Agent is idle or actively generating a response.

See protocol docs: Session Modes

SetSessionModeRequest

Request parameters for setting a session mode.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="modeId" type={SessionModeId} required

The ID of the mode to set. <ResponseField name="sessionId" type={SessionId} required

The ID of the session to set the mode for.

SetSessionModeResponse

Response to session/set_mode method.

Type: Object

Properties:

<ResponseField name="meta" type={"object"}>

Client

Defines the interface that ACP-compliant clients must implement.

Clients are typically code editors (IDEs, text editors) that provide the interface between users and AI agents. They manage the environment, handle user interactions, and control access to resources.

fs/read_text_file

Reads content from a text file in the client's file system.

Only available if the client advertises the fs.readTextFile capability. Allows the agent to access file contents within the client's environment.

See protocol docs: Client

ReadTextFileRequest

Request to read content from a text file.

Only available if the client supports the fs.readTextFile capability.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="limit" type={"integer | null"} > Maximum number of lines to read.

- Minimum: `0`

Line number to start reading from (1-based).

- Minimum: `0`

Absolute path to the file to read. SessionId} required> The session ID for this request.

ReadTextFileResponse

Response containing the contents of a text file.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="content" type={"string"} required>

fs/write_text_file

Writes content to a text file in the client's file system.

Only available if the client advertises the fs.writeTextFile capability. Allows the agent to create or modify files within the client's environment.

See protocol docs: Client

WriteTextFileRequest

Request to write content to a text file.

Only available if the client supports the fs.writeTextFile capability.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="content" type={"string"} required> The text content to write to the file. <ResponseField name="path" type={"string"} required> Absolute path to the file to write. <ResponseField name="sessionId" type={SessionId} required

The session ID for this request.

WriteTextFileResponse

Response to fs/write_text_file

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations

session/request_permission

Requests permission from the user for a tool call operation.

Called by the agent when it needs user authorization before executing a potentially sensitive operation. The client should present the options to the user and return their decision.

If the client cancels the prompt turn via session/cancel, it MUST respond to this request with RequestPermissionOutcome::Cancelled.

See protocol docs: Requesting Permission

RequestPermissionRequest

Request for user permission to execute a tool call.

Sent when the agent needs authorization before performing a sensitive operation.

See protocol docs: Requesting Permission

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="options" type={ <> PermissionOption [] </> } required

Available permission options for the user to choose from. <ResponseField name="sessionId" type={SessionId} required

The session ID for this request. <ResponseField name="toolCall" type={ToolCallUpdate} required

Details about the tool call requiring permission.

RequestPermissionResponse

Response to a permission request.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="outcome" type={RequestPermissionOutcome} required

The user's decision on the permission request.

session/update

Handles session update notifications from the agent.

This is a notification endpoint (no response expected) that receives real-time updates about session progress, including message chunks, tool calls, and execution plans.

Note: Clients SHOULD continue accepting tool call updates even after sending a session/cancel notification, as the agent may send final updates before responding with the cancelled stop reason.

See protocol docs: Agent Reports Output

SessionNotification

Notification containing a session update from the agent.

Used to stream real-time progress and results during prompt processing.

See protocol docs: Agent Reports Output

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="sessionId" type={SessionId} required

The ID of the session this update pertains to. <ResponseField name="update" type={SessionUpdate} required

The actual update content.

terminal/create

Executes a command in a new terminal

Only available if the terminal Client capability is set to true.

Returns a TerminalId that can be used with other terminal methods to get the current output, wait for exit, and kill the command.

The TerminalId can also be used to embed the terminal in a tool call by using the ToolCallContent::Terminal variant.

The Agent is responsible for releasing the terminal by using the terminal/release method.

See protocol docs: Terminals

CreateTerminalRequest

Request to create a new terminal and execute a command.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="args" type={<>"string"[]</>} > Array of command arguments. <ResponseField name="command" type={"string"} required> The command to execute. <ResponseField name="cwd" type={"string | null"} > Working directory for the command (absolute path). <ResponseField name="env" type={<>EnvVariable[]</>} > Environment variables for the command. <ResponseField name="outputByteLimit" type={"integer | null"} > Maximum number of output bytes to retain.

When the limit is exceeded, the Client truncates from the beginning of the output to stay within the limit.

The Client MUST ensure truncation happens at a character boundary to maintain valid string output, even if this means the retained output is slightly less than the specified limit.

- Minimum: `0`

SessionId} required> The session ID for this request.

CreateTerminalResponse

Response containing the ID of the created terminal.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="terminalId" type={"string"} required> The unique identifier for the created terminal.

terminal/kill

Kills the terminal command without releasing the terminal

While terminal/release will also kill the command, this method will keep the TerminalId valid so it can be used with other methods.

This method can be helpful when implementing command timeouts which terminate the command as soon as elapsed, and then get the final output so it can be sent to the model.

Note: terminal/release when TerminalId is no longer needed.

See protocol docs: Terminals

KillTerminalCommandRequest

Request to kill a terminal command without releasing the terminal.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="sessionId" type={SessionId} required

The session ID for this request. <ResponseField name="terminalId" type={"string"} required> The ID of the terminal to kill.

KillTerminalCommandResponse

Response to terminal/kill command method

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations

terminal/output

Gets the terminal output and exit status

Returns the current content in the terminal without waiting for the command to exit. If the command has already exited, the exit status is included.

See protocol docs: Terminals

TerminalOutputRequest

Request to get the current output and status of a terminal.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="sessionId" type={SessionId} required

The session ID for this request. <ResponseField name="terminalId" type={"string"} required> The ID of the terminal to get output from.

TerminalOutputResponse

Response containing the terminal output and exit status.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="exitStatus" type={ <> TerminalExitStatus | null </> }

Exit status if the command has completed. <ResponseField name="output" type={"string"} required> The terminal output captured so far. <ResponseField name="truncated" type={"boolean"} required> Whether the output was truncated due to byte limits.

terminal/release

Releases a terminal

The command is killed if it hasn't exited yet. Use terminal/wait_for_exit to wait for the command to exit before releasing the terminal.

After release, the TerminalId can no longer be used with other terminal/* methods, but tool calls that already contain it, continue to display its output.

The terminal/kill method can be used to terminate the command without releasing the terminal, allowing the Agent to call terminal/output and other methods.

See protocol docs: Terminals

ReleaseTerminalRequest

Request to release a terminal and free its resources.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="sessionId" type={SessionId} required

The session ID for this request. <ResponseField name="terminalId" type={"string"} required> The ID of the terminal to release.

ReleaseTerminalResponse

Response to terminal/release method

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations

terminal/wait_for_exit

Waits for the terminal command to exit and return its exit status

See protocol docs: Terminals

WaitForTerminalExitRequest

Request to wait for a terminal command to exit.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="sessionId" type={SessionId} required

The session ID for this request. <ResponseField name="terminalId" type={"string"} required> The ID of the terminal to wait for.

WaitForTerminalExitResponse

Response containing the exit status of a terminal command.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="exitCode" type={"integer | null"} > The process exit code (may be null if terminated by signal).

- Minimum: `0`

The signal that terminated the process (may be null if exited normally).

AgentCapabilities

Capabilities supported by the agent.

Advertised during initialization to inform the client about available features and content types.

See protocol docs: Agent Capabilities

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="loadSession" type={"boolean"} > Whether the agent supports session/load.

- Default: `false`

McpCapabilities} > MCP capabilities supported by the agent.

- Default: `{"http":false,"sse":false}`

PromptCapabilities} > Prompt capabilities supported by the agent.

- Default: `{"audio":false,"embeddedContext":false,"image":false}`

Annotations

Optional annotations for the client. The client can use annotations to inform how objects are used or displayed

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="audience" type={"array | null"}> <ResponseField name="lastModified" type={"string | null"}> <ResponseField name="priority" type={"number | null"}>

AudioContent

Audio provided to or from an LLM.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="annotations" type={ <> Annotations | null </> }

<ResponseField name="data" type={"string"} required> <ResponseField name="mimeType" type={"string"} required>

AuthMethod

Describes an available authentication method.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="description" type={"string | null"}> Optional description providing more details about this authentication method. <ResponseField name="id" type={AuthMethodId} required

Unique identifier for this authentication method. <ResponseField name="name" type={"string"} required> Human-readable name of the authentication method.

AuthMethodId

Unique identifier for an authentication method.

Type: string

AvailableCommand

Information about a command.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="description" type={"string"} required> Human-readable description of what the command does. <ResponseField name="input" type={ <> AvailableCommandInput | null </> }

Input for the command if required <ResponseField name="name" type={"string"} required> Command name (e.g., "create_plan", "research_codebase").

AvailableCommandInput

The input specification for a command.

Type: Union

All text that was typed after the command name is provided as input.

<ResponseField name="hint" type={"string"} required> A hint to display when the input hasn't been provided yet

BlobResourceContents

Binary resource contents.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="blob" type={"string"} required> <ResponseField name="mimeType" type={"string | null"}> <ResponseField name="uri" type={"string"} required>

ClientCapabilities

Capabilities supported by the client.

Advertised during initialization to inform the agent about available features and methods.

See protocol docs: Client Capabilities

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="fs" type={FileSystemCapability} > File system capabilities supported by the client. Determines which file operations the agent can request.

- Default: `{"readTextFile":false,"writeTextFile":false}`

Whether the Client support all `terminal/*` methods.

- Default: `false`

ContentBlock

Content blocks represent displayable information in the Agent Client Protocol.

They provide a structured way to handle various types of user-facing content—whether it's text from language models, images for analysis, or embedded resources for context.

Content blocks appear in:

• User prompts sent via session/prompt
• Language model output streamed through session/update notifications
• Progress updates and results from tool calls

This structure is compatible with the Model Context Protocol (MCP), enabling agents to seamlessly forward content from MCP tool outputs without transformation.

See protocol docs: Content

Type: Union

Plain text content

All agents MUST support text content blocks in prompts.

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="annotations" type={ <> Annotations | null </> }

<ResponseField name="text" type={"string"} required> <ResponseField name="type" type={"string"} required>

Images for visual context or analysis.

Requires the image prompt capability when included in prompts.

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="annotations" type={ <> Annotations | null </> }

<ResponseField name="data" type={"string"} required> <ResponseField name="mimeType" type={"string"} required> <ResponseField name="type" type={"string"} required> <ResponseField name="uri" type={"string | null"}>

Audio data for transcription or analysis.

Requires the audio prompt capability when included in prompts.

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="annotations" type={ <> Annotations | null </> }

<ResponseField name="data" type={"string"} required> <ResponseField name="mimeType" type={"string"} required> <ResponseField name="type" type={"string"} required>

References to resources that the agent can access.

All agents MUST support resource links in prompts.

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="annotations" type={ <> Annotations | null </> }

<ResponseField name="description" type={"string | null"}> <ResponseField name="mimeType" type={"string | null"}> <ResponseField name="name" type={"string"} required> <ResponseField name="size" type={"integer | null"}> <ResponseField name="title" type={"string | null"}> <ResponseField name="type" type={"string"} required> <ResponseField name="uri" type={"string"} required>

Complete resource contents embedded directly in the message.

Preferred for including context as it avoids extra round-trips.

Requires the embeddedContext prompt capability when included in prompts.

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="annotations" type={ <> Annotations | null </> }

<ResponseField name="resource" type={EmbeddedResourceResource} required

<ResponseField name="type" type={"string"} required>

EmbeddedResource

The contents of a resource, embedded into a prompt or tool call result.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="annotations" type={ <> Annotations | null </> }

<ResponseField name="resource" type={EmbeddedResourceResource} required

EmbeddedResourceResource

Resource content that can be embedded in a message.

Type: Union

{""}

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="mimeType" type={"string | null"}> <ResponseField name="text" type={"string"} required> <ResponseField name="uri" type={"string"} required>

{""}

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="blob" type={"string"} required> <ResponseField name="mimeType" type={"string | null"}> <ResponseField name="uri" type={"string"} required>

EnvVariable

An environment variable to set when launching an MCP server.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="name" type={"string"} required> The name of the environment variable. <ResponseField name="value" type={"string"} required> The value to set for the environment variable.

FileSystemCapability

File system capabilities that a client may support.

See protocol docs: FileSystem

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="readTextFile" type={"boolean"} > Whether the Client supports fs/read_text_file requests.

- Default: `false`

Whether the Client supports `fs/write_text_file` requests.

- Default: `false`

HttpHeader

An HTTP header to set when making requests to the MCP server.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="name" type={"string"} required> The name of the HTTP header. <ResponseField name="value" type={"string"} required> The value to set for the HTTP header.

ImageContent

An image provided to or from an LLM.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="annotations" type={ <> Annotations | null </> }

<ResponseField name="data" type={"string"} required> <ResponseField name="mimeType" type={"string"} required> <ResponseField name="uri" type={"string | null"}>

McpCapabilities

MCP capabilities supported by the agent

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="http" type={"boolean"} > Agent supports McpServer::Http.

- Default: `false`

Agent supports `McpServer::Sse`.

- Default: `false`

McpServer

Configuration for connecting to an MCP (Model Context Protocol) server.

MCP servers provide tools and context that the agent can use when processing prompts.

See protocol docs: MCP Servers

Type: Union

HTTP transport configuration

Only available when the Agent capabilities indicate mcp_capabilities.http is true.

<ResponseField name="headers" type={ <> HttpHeader [] </> } required

HTTP headers to set when making requests to the MCP server. <ResponseField name="name" type={"string"} required> Human-readable name identifying this MCP server. <ResponseField name="type" type={"string"} required> <ResponseField name="url" type={"string"} required> URL to the MCP server.

SSE transport configuration

Only available when the Agent capabilities indicate mcp_capabilities.sse is true.

<ResponseField name="headers" type={ <> HttpHeader [] </> } required

HTTP headers to set when making requests to the MCP server. <ResponseField name="name" type={"string"} required> Human-readable name identifying this MCP server. <ResponseField name="type" type={"string"} required> <ResponseField name="url" type={"string"} required> URL to the MCP server.

Stdio transport configuration

All Agents MUST support this transport.

<ResponseField name="args" type={ <> "string" [] </> } required

Command-line arguments to pass to the MCP server. <ResponseField name="command" type={"string"} required> Path to the MCP server executable. <ResponseField name="env" type={ <> EnvVariable [] </> } required

Environment variables to set when launching the MCP server. <ResponseField name="name" type={"string"} required> Human-readable name identifying this MCP server.

PermissionOption

An option presented to the user when requesting permission.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="kind" type={PermissionOptionKind} required

Hint about the nature of this permission option. <ResponseField name="name" type={"string"} required> Human-readable label to display to the user. <ResponseField name="optionId" type={PermissionOptionId} required

Unique identifier for this permission option.

PermissionOptionId

Unique identifier for a permission option.

Type: string

PermissionOptionKind

The type of permission option being presented to the user.

Helps clients choose appropriate icons and UI treatment.

Type: Union

Allow this operation only this time. Allow this operation and remember the choice. Reject this operation only this time. Reject this operation and remember the choice.

Plan

An execution plan for accomplishing complex tasks.

Plans consist of multiple entries representing individual tasks or goals. Agents report plans to clients to provide visibility into their execution strategy. Plans can evolve during execution as the agent discovers new requirements or completes tasks.

See protocol docs: Agent Plan

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="entries" type={<>PlanEntry[]</>} required> The list of tasks to be accomplished.

When updating a plan, the agent must send a complete list of all entries with their current status. The client replaces the entire plan with each update.

PlanEntry

A single entry in the execution plan.

Represents a task or goal that the assistant intends to accomplish as part of fulfilling the user's request. See protocol docs: Plan Entries

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="content" type={"string"} required> Human-readable description of what this task aims to accomplish. <ResponseField name="priority" type={PlanEntryPriority} required

The relative importance of this task. Used to indicate which tasks are most critical to the overall goal. <ResponseField name="status" type={PlanEntryStatus} required

Current execution status of this task.

PlanEntryPriority

Priority levels for plan entries.

Used to indicate the relative importance or urgency of different tasks in the execution plan. See protocol docs: Plan Entries

Type: Union

High priority task - critical to the overall goal. Medium priority task - important but not critical. Low priority task - nice to have but not essential.

PlanEntryStatus

Status of a plan entry in the execution flow.

Tracks the lifecycle of each task from planning through completion. See protocol docs: Plan Entries

Type: Union

The task has not started yet.

The task is currently being worked on. The task has been successfully completed.

PromptCapabilities

Prompt capabilities supported by the agent in session/prompt requests.

Baseline agent functionality requires support for ContentBlock::Text and ContentBlock::ResourceLink in prompt requests.

Other variants must be explicitly opted in to. Capabilities for different types of content in prompt requests.

Indicates which content types beyond the baseline (text and resource links) the agent can process.

See protocol docs: Prompt Capabilities

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="audio" type={"boolean"} > Agent supports ContentBlock::Audio.

- Default: `false`

Agent supports embedded context in `session/prompt` requests.

When enabled, the Client is allowed to include ContentBlock::Resource in prompt requests for pieces of context that are referenced in the message.

- Default: `false`

Agent supports `ContentBlock::Image`.

- Default: `false`

ProtocolVersion

Protocol version identifier.

This version is only bumped for breaking changes. Non-breaking changes should be introduced via capabilities.

Type: integer (uint16)

Constraint	Value
Minimum	0
Maximum	65535

RequestPermissionOutcome

The outcome of a permission request.

Type: Union

The prompt turn was cancelled before the user responded.

When a client sends a session/cancel notification to cancel an ongoing prompt turn, it MUST respond to all pending session/request_permission requests with this Cancelled outcome.

See protocol docs: Cancellation

<ResponseField name="outcome" type={"string"} required>

The user selected one of the provided options.

<ResponseField name="optionId" type={PermissionOptionId} required

The ID of the option the user selected. <ResponseField name="outcome" type={"string"} required>

ResourceLink

A resource that the server is capable of reading, included in a prompt or tool call result.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="annotations" type={ <> Annotations | null </> }

<ResponseField name="description" type={"string | null"}> <ResponseField name="mimeType" type={"string | null"}> <ResponseField name="name" type={"string"} required> <ResponseField name="size" type={"integer | null"}> <ResponseField name="title" type={"string | null"}> <ResponseField name="uri" type={"string"} required>

Role

The sender or recipient of messages and data in a conversation.

Type: Enumeration

Value
"assistant"
"user"

SessionId

A unique identifier for a conversation session between a client and agent.

Sessions maintain their own context, conversation history, and state, allowing multiple independent interactions with the same agent.

# Example

use agent_client_protocol::SessionId;
use std::sync::Arc;

let session_id = SessionId(Arc::from("sess_abc123def456"));

See protocol docs: Session ID

Type: string

SessionMode

A mode the agent can operate in.

See protocol docs: Session Modes

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="description" type={"string | null"}> <ResponseField name="id" type={SessionModeId} required

<ResponseField name="name" type={"string"} required>

SessionModeId

Unique identifier for a Session Mode.

Type: string

SessionModeState

The set of modes and the one currently active.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="availableModes" type={ <> SessionMode [] </> } required

The set of modes that the Agent can operate in <ResponseField name="currentModeId" type={SessionModeId} required

The current mode the Agent is in.

SessionUpdate

Different types of updates that can be sent during session processing.

These updates provide real-time feedback about the agent's progress.

See protocol docs: Agent Reports Output

Type: Union

A chunk of the user's message being streamed.

<ResponseField name="content" type={ContentBlock} required

<ResponseField name="sessionUpdate" type={"string"} required>

A chunk of the agent's response being streamed.

<ResponseField name="content" type={ContentBlock} required

<ResponseField name="sessionUpdate" type={"string"} required>

A chunk of the agent's internal reasoning being streamed.

<ResponseField name="content" type={ContentBlock} required

<ResponseField name="sessionUpdate" type={"string"} required>

Notification that a new tool call has been initiated.

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="content" type={ <> ToolCallContent [] </> }

Content produced by the tool call. <ResponseField name="kind" type={ToolKind}> The category of tool being invoked. Helps clients choose appropriate icons and UI treatment. <ResponseField name="locations" type={ <> ToolCallLocation [] </> }

File locations affected by this tool call. Enables "follow-along" features in clients. <ResponseField name="rawInput" type={"object"}> Raw input parameters sent to the tool. <ResponseField name="rawOutput" type={"object"}> Raw output returned by the tool. <ResponseField name="sessionUpdate" type={"string"} required> <ResponseField name="status" type={ToolCallStatus}

Current execution status of the tool call. <ResponseField name="title" type={"string"} required> Human-readable title describing what the tool is doing. <ResponseField name="toolCallId" type={ToolCallId} required

Unique identifier for this tool call within the session.

Update on the status or results of a tool call.

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="content" type={"array | null"}> Replace the content collection. <ResponseField name="kind" type={ <> ToolKind | null </> }

Update the tool kind. <ResponseField name="locations" type={"array | null"}> Replace the locations collection. <ResponseField name="rawInput" type={"object"}> Update the raw input. <ResponseField name="rawOutput" type={"object"}> Update the raw output. <ResponseField name="sessionUpdate" type={"string"} required> <ResponseField name="status" type={ <> ToolCallStatus | null </> }

Update the execution status. <ResponseField name="title" type={"string | null"}> Update the human-readable title. <ResponseField name="toolCallId" type={ToolCallId} required

The ID of the tool call being updated.

The agent's execution plan for complex tasks. See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="entries" type={<>PlanEntry[]</>} required> The list of tasks to be accomplished.

When updating a plan, the agent must send a complete list of all entries with their current status. The client replaces the entire plan with each update.

Available commands are ready or have changed

<ResponseField name="availableCommands" type={ <> AvailableCommand [] </> } required

<ResponseField name="sessionUpdate" type={"string"} required>

The current mode of the session has changed

See protocol docs: Session Modes

<ResponseField name="currentModeId" type={SessionModeId} required

<ResponseField name="sessionUpdate" type={"string"} required>

StopReason

Reasons why an agent stops processing a prompt turn.

See protocol docs: Stop Reasons

Type: Union

The turn ended successfully.

The turn ended because the agent reached the maximum number of tokens. The turn ended because the agent reached the maximum number of allowed agent requests between user turns. The turn ended because the agent refused to continue. The user prompt and everything that comes after it won't be included in the next prompt, so this should be reflected in the UI. The turn was cancelled by the client via `session/cancel`.

This stop reason MUST be returned when the client sends a session/cancel notification, even if the cancellation causes exceptions in underlying operations. Agents should catch these exceptions and return this semantically meaningful response to confirm successful cancellation.

TerminalExitStatus

Exit status of a terminal command.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="exitCode" type={"integer | null"} > The process exit code (may be null if terminated by signal).

- Minimum: `0`

The signal that terminated the process (may be null if exited normally).

TextContent

Text provided to or from an LLM.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="annotations" type={ <> Annotations | null </> }

<ResponseField name="text" type={"string"} required>

TextResourceContents

Text-based resource contents.

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="mimeType" type={"string | null"}> <ResponseField name="text" type={"string"} required> <ResponseField name="uri" type={"string"} required>

ToolCall

Represents a tool call that the language model has requested.

Tool calls are actions that the agent executes on behalf of the language model, such as reading files, executing code, or fetching data from external sources.

See protocol docs: Tool Calls

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="content" type={ <> ToolCallContent [] </> }

Content produced by the tool call. <ResponseField name="kind" type={ToolKind}> The category of tool being invoked. Helps clients choose appropriate icons and UI treatment. <ResponseField name="locations" type={ <> ToolCallLocation [] </> }

File locations affected by this tool call. Enables "follow-along" features in clients. <ResponseField name="rawInput" type={"object"}> Raw input parameters sent to the tool. <ResponseField name="rawOutput" type={"object"}> Raw output returned by the tool. <ResponseField name="status" type={ToolCallStatus}

Current execution status of the tool call. <ResponseField name="title" type={"string"} required> Human-readable title describing what the tool is doing. <ResponseField name="toolCallId" type={ToolCallId} required

Unique identifier for this tool call within the session.

ToolCallContent

Content produced by a tool call.

Tool calls can produce different types of content including standard content blocks (text, images) or file diffs.

See protocol docs: Content

Type: Union

Standard content block (text, images, resources).

<ResponseField name="content" type={ContentBlock} required

The actual content block. <ResponseField name="type" type={"string"} required>

File modification shown as a diff.

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="newText" type={"string"} required> The new content after modification. <ResponseField name="oldText" type={"string | null"}> The original content (None for new files). <ResponseField name="path" type={"string"} required> The file path being modified. <ResponseField name="type" type={"string"} required>

Embed a terminal created with `terminal/create` by its id.

The terminal must be added before calling terminal/release.

See protocol docs: Terminal

<ResponseField name="terminalId" type={"string"} required> <ResponseField name="type" type={"string"} required>

ToolCallId

Unique identifier for a tool call within a session.

Type: string

ToolCallLocation

A file location being accessed or modified by a tool.

Enables clients to implement "follow-along" features that track which files the agent is working with in real-time.

See protocol docs: Following the Agent

Type: Object

Properties:

<ResponseField name="_meta" type={"object"} > Extension point for implementations <ResponseField name="line" type={"integer | null"} > Optional line number within the file.

- Minimum: `0`

The file path being accessed or modified.

ToolCallStatus

Execution status of a tool call.

Tool calls progress through different statuses during their lifecycle.

See protocol docs: Status

Type: Union

The tool call hasn't started running yet because the input is either streaming or we're awaiting approval. The tool call is currently running. The tool call completed successfully.

The tool call failed with an error.

ToolCallUpdate

An update to an existing tool call.

Used to report progress and results as tools execute. All fields except the tool call ID are optional - only changed fields need to be included.

See protocol docs: Updating

Type: Object

Properties:

<ResponseField name="_meta" type={"object"}> Extension point for implementations <ResponseField name="content" type={"array | null"}> Replace the content collection. <ResponseField name="kind" type={ <> ToolKind | null </> }

Update the tool kind. <ResponseField name="locations" type={"array | null"}> Replace the locations collection. <ResponseField name="rawInput" type={"object"}> Update the raw input. <ResponseField name="rawOutput" type={"object"}> Update the raw output. <ResponseField name="status" type={ <> ToolCallStatus | null </> }

Update the execution status. <ResponseField name="title" type={"string | null"}> Update the human-readable title. <ResponseField name="toolCallId" type={ToolCallId} required

The ID of the tool call being updated.

ToolKind

Categories of tools that can be invoked.

Tool kinds help clients choose appropriate icons and optimize how they display tool execution progress.

See protocol docs: Creating

Type: Union

Reading files or data.

Modifying files or content.

Removing files or data.

Moving or renaming files.

Searching for information.

Running commands or code.

Internal reasoning or planning.

Retrieving external data.

Switching the current session mode.

Other tool types (default).