MCP (Model Context Protocol) client for consuming external tool servers.

One JSON-RPC session machine over a pluggable transport: it performs the initialize handshake where the peer's era requires one, discovers available tools via tools/list, and executes tool calls via tools/call. The wire is Raxol.MCP.Client.Transport (ADR-0037 decision 1): a local subprocess (Transport.Stdio) or a hosted HTTPS endpoint (Transport.Http).

Usage

{:ok, client} = Client.start_link(
  name: :my_server,
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
)

{:ok, remote} = Client.start_link(
  name: :intel,
  url: "https://mcp.example.com/mcp",
  headers: [{"authorization", "Bearer ..."}]
)

{:ok, tools} = Client.list_tools(client)
{:ok, result} = Client.call_tool(client, "read_file", %{path: "/tmp/hello.txt"})
Client.stop(client)

The spec discriminator is :command XOR :url. A spec carrying both, or neither, is {:error, {:invalid_spec, spec}} with its header values redacted; a :url spec in a build without mint is {:error, :no_http_client}.

Header values reaching this module are ALREADY RESOLVED LITERALS. Nothing here reads ${env:VAR} or op://...: resolution and the provenance rule that gates it live in raxol_agent, where .mcp.json is parsed.

Concurrency and the in-flight window

A GenServer serializes calls on entry, which is not the same as bounding the requests in flight: two callers used to get two concurrent requests on one session, and a TronScan-shaped upstream answers 500 to both (docs/proposals/web3-upstream-survey.md:72-78). So the window is explicit (ADR-0037 decision 6). :concurrency is :stateless, :pooled or :serialized; every policy has a finite in-flight cap, and a :serialized origin has a cap of one. Excess work waits in a bounded queue that answers {:error, :busy} on overflow rather than admitting work it cannot start.

Every admitted request carries a timer. On expiry the client replies {:error, :timeout} itself and drops the entry, which is what stops pending from growing without bound: before this, an entry was removed only by a reply, a JSON-RPC error or a subprocess exit status, and a caller whose GenServer.call timed out left its entry behind forever. An HTTP transport has no exit status at all.

Recovery

A connect that fails, and a handshake that fails, both land the client in :closed carrying the reason and schedule a retry whose delay starts at :reconnect_ms (1 s) and doubles to one minute. Nothing here stops the process: start_link/1 links the CALLER, so a {:stop, _} would take the agent down over one bad spec. A session the origin rejects mid-flight fails that one request and is re-established in place, on the same handle.

The exception is a 401 at connect or handshake: the headers were resolved once, so a retry could only present the same rejected credential. The client stays :closed with {:connect_failed, reason}, schedules nothing, and answers any await_ready/2 caller at once. The credential's owner replaces the client.

A spec with fail_fast: true keeps the retry but stops await_ready/2 from waiting through it: each failed connect or handshake answers the callers already waiting with {:error, {:connect_failed, reason}}, and a caller that arrives while the client is still :closed after that failure gets the same answer at once. An owner that runs its own retry policy (and stops this client to do so) uses it to see the failure at once instead of at its deadline.

Tool Namespacing

Tools are namespaced with the server name prefix: mcp__<server>__<tool>. Use tool_name/2 to build namespaced names, and parse_tool_name/1 to decompose them.