A client for Model Context Protocol servers over stdio or opt-in Streamable HTTP, exposing tools as ExAgent.Tools.

For HTTP use transport: :streamable_http, url: url, finch: MyFinch and an application-owned HTTP1-only pool. See ExAgent.MCP.StreamableHTTP for limits and configuration preconditions. HTTP uses MCP2025-06-18; stdio is unchanged. After a session404, reconnect/1 explicitly starts a new handshake. No tool request is replayed. Direct call_tool/3 is transport IO, not runtime approval. Generated tools use the normal validation and permission boundary. Persisted continuation requires explicit trusted endpoint/principal references through :continuation_binding; ordinary tools work without those references.

An MCP server is an external process that speaks JSON-RPC 2.0 over stdin/stdout (e.g. npx -y @modelcontextprotocol/server-filesystem ./). This client spawns it, performs the initialize handshake, lists its tools, and turns each into an ExAgent.Tool whose execution forwards a tools/call back to the server.

Example

chat_model is an explicitly configured ExAgent.Models.ReqLLM instance with credentials and the qualified tool profile (see the README recipe).

# 1) start the server + handshake
{:ok, client} =
  ExAgent.MCP.Client.start_link(
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
  )

# 2) discover its tools as ExAgent tools
{:ok, tools} = ExAgent.MCP.Client.tools(client)

# 3) use them like any ExAgent tool
agent = ExAgent.new(model: chat_model, tools: tools)
ExAgent.run(agent, "list the files")

Concurrency and request ownership

A client owns one transport. Requests are sent independently and can execute concurrently on the remote server; the GenServer does not serialize remote tool effects. Each pending request has a deadline and monitors its caller. A timeout returns {:error, :timeout} and caller death drops the local request. Neither proves that a remote tool stopped or rolled back, and neither triggers replay. Requests beyond :max_pending return {:error, :busy} before sending.

Incoming newline-delimited frames are limited by :max_frame_bytes. An oversized frame closes the transport, fails remaining pending requests, and leaves the client not ready. Complete responses preceding that frame are processed first, independently of transport chunk boundaries. These bounds limit pending state and individual frames, not the BEAM mailbox or aggregate traffic from a push transport.

Testing seam

The transport is pluggable: pass transport: {send_fun, ref} (mostly for tests) to inject a fake transport instead of spawning a real process. The client receives data as messages shaped {ref, {:data, binary}}. send_fun must return promptly: it runs in the client process, so a blocking callback delays deadlines and other client operations. {:error, reason}, false, exceptions and throws/exits indicate an unconfirmed send; other return values (including the value returned by send/2) retain their existing meaning.