ExMCP.Client.CallbackHandler (ex_mcp v0.10.0)

Callback-based handler for MCP client events.

Routes server-initiated requests (elicitation, sampling, roots) to user-provided callback functions. This allows any UI framework to integrate with MCP without implementing the full Handler behaviour.

Usage

{:ok, client} = ExMCP.Client.start_link(
  transport: :http,
  url: "http://localhost:3000/mcp",
  handler: {ExMCP.Client.CallbackHandler, [
    on_elicitation: fn message, schema ->
      # Present to your UI and collect response
      {:ok, %{"name" => "Alice", "age" => 30}}
    end,
    on_sampling: fn params ->
      # Handle sampling/createMessage request
      {:ok, %{"role" => "assistant", "content" => %{"type" => "text", "text" => "Hello"}}}
    end,
    on_roots: fn ->
      # Return list of roots
      {:ok, [%{"uri" => "file:///workspace", "name" => "workspace"}]}
    end
  ]},
  capabilities: %{"elicitation" => %{}, "sampling" => %{}}
)

Callbacks

All callbacks are optional. When not provided, the handler declines elicitations, returns empty roots, and rejects sampling requests.

on_elicitation

fn message :: String.t(), requested_schema :: map() ->
  {:ok, content :: map()}      # accept with data
  | :decline                    # decline the request
  | :cancel                     # cancel the operation
  | {:error, reason}            # error
end

on_sampling

fn params :: map() ->
  {:ok, result :: map()}        # sampling result
  | {:error, reason}            # error
end

on_roots

fn ->
  {:ok, roots :: [map()]}       # list of root URIs
  | {:error, reason}            # error
end