ExMCP.ACP.Client (ex_mcp v0.9.0)
View SourceGenServer client for the Agent Client Protocol (ACP).
Manages connections to ACP-compatible coding agents over stdio, handling the initialize handshake, session lifecycle, and bidirectional communication (streaming updates from agent, permission/file requests from agent).
Usage
{:ok, client} = ExMCP.ACP.Client.start_link(
command: ["gemini", "--acp"],
handler: MyApp.ACPHandler
)
{:ok, %{"sessionId" => sid}} = ExMCP.ACP.Client.new_session(client, "/path/to/project")
{:ok, %{"stopReason" => _}} = ExMCP.ACP.Client.prompt(client, sid, "Fix the bug in auth.ex")Options
:command— command list for the agent subprocess (required):handler— module implementingExMCP.ACP.Client.Handler(default:DefaultHandler):handler_opts— options passed tohandler.init/1(default:[]):event_listener— PID to receive{:acp_session_update, session_id, update}messages:client_info—%{"name" => ..., "version" => ...}(default:%{"name" => "ex_mcp", "version" => "0.1.0"}):capabilities— client capabilities map:protocol_version— integer (default: 1):name— GenServer name registration
Summary
Functions
Returns the agent's capabilities from the initialize handshake.
Authenticates with the agent.
Cancels the current prompt in a session (fire-and-forget).
Returns a specification to start this module under a supervisor.
Disconnects from the agent.
Lists available sessions from the agent. Stabilized in ACP spec March 9, 2026.
Loads (resumes) an existing session.
Creates a new agent session.
Sends a prompt to the agent and blocks until the response arrives.
Sets a config option for a session.
Sets the agent mode for a session.
Starts the ACP client and connects to the agent.
Returns the client connection status.
Functions
@spec agent_capabilities(GenServer.server()) :: {:ok, map() | nil}
Returns the agent's capabilities from the initialize handshake.
@spec authenticate(GenServer.server(), map(), keyword()) :: {:ok, map()} | {:error, any()}
Authenticates with the agent.
Authentication is currently in RFD draft stage in the ACP spec. Sends provider-specific authentication parameters.
@spec cancel(GenServer.server(), String.t()) :: :ok
Cancels the current prompt in a session (fire-and-forget).
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec disconnect(GenServer.server()) :: :ok
Disconnects from the agent.
@spec list_sessions( GenServer.server(), keyword() ) :: {:ok, map()} | {:error, any()}
Lists available sessions from the agent. Stabilized in ACP spec March 9, 2026.
@spec load_session(GenServer.server(), String.t(), String.t() | nil, keyword()) :: {:ok, map()} | {:error, any()}
Loads (resumes) an existing session.
@spec new_session(GenServer.server(), String.t() | nil, keyword()) :: {:ok, map()} | {:error, any()}
Creates a new agent session.
@spec prompt(GenServer.server(), String.t(), String.t() | [map()], keyword()) :: {:ok, map()} | {:error, any()}
Sends a prompt to the agent and blocks until the response arrives.
Streaming session/update notifications are delivered to the handler and
event listener as they arrive. The caller is unblocked when the agent sends
the JSON-RPC result for the prompt request.
@spec set_config_option(GenServer.server(), String.t(), String.t(), any()) :: {:ok, map()} | {:error, any()}
Sets a config option for a session.
@spec set_mode(GenServer.server(), String.t(), String.t()) :: {:ok, map()} | {:error, any()}
Sets the agent mode for a session.
@spec start_link(keyword()) :: GenServer.on_start()
Starts the ACP client and connects to the agent.
@spec status(GenServer.server()) :: atom()
Returns the client connection status.