# `ExMCP.Client.CallbackHandler`
[🔗](https://github.com/azmaveth/ex_mcp/blob/v1.0.0/lib/ex_mcp/client/callback_handler.ex#L1)

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*