Raxol.MCP.Client (Raxol MCP v2.6.0)

Copy Markdown View Source

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

Manages a stdio-based MCP server process: spawns it, performs the initialize handshake, discovers available tools via tools/list, and executes tool calls via tools/call.

Usage

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

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

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.

Summary

Types

call_result()
t()
tool()

Functions

call_tool(server, tool_name, arguments \\ %{}, opts \\ [])

Call a tool on the MCP server.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

handle_manager_cast(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_cast/2.

list_tools(server, opts \\ [])

List tools available on the MCP server.

parse_tool_name(arg1)

Parse a namespaced tool name into {server, tool} or :error.

start_link(init_opts \\ [])

Start an MCP client linked to the calling process.

status(server)

Get the client's current status.

stop(server)

Stop the MCP server and client.

tool_name(server_name, tool)

Build a namespaced tool name: mcp__<server>__<tool>.

Types

call_result()

@type call_result() :: %{content: [map()], is_error: boolean()}

t()

@type t() :: %Raxol.MCP.Client{
  args: [String.t()],
  buffer: String.t(),
  call_timeout: pos_integer(),
  command: String.t(),
  env: [{String.t(), String.t()}],
  name: atom(),
  next_id: pos_integer(),
  pending: %{required(pos_integer()) => GenServer.from() | :init},
  port: port() | nil,
  registry: atom() | nil,
  status: :starting | :initializing | :ready | :closed,
  tools: [tool()] | nil
}

tool()

@type tool() :: %{name: String.t(), description: String.t(), input_schema: map()}

Functions

call_tool(server, tool_name, arguments \\ %{}, opts \\ [])

@spec call_tool(GenServer.server(), String.t(), map(), keyword()) ::
  {:ok, call_result()} | {:error, term()}

Call a tool on the MCP server.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

handle_manager_cast(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_cast/2.

list_tools(server, opts \\ [])

@spec list_tools(
  GenServer.server(),
  keyword()
) :: {:ok, [tool()]} | {:error, term()}

List tools available on the MCP server.

parse_tool_name(arg1)

@spec parse_tool_name(String.t()) :: {:ok, {String.t(), String.t()}} | :error

Parse a namespaced tool name into {server, tool} or :error.

start_link(init_opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Start an MCP client linked to the calling process.

status(server)

@spec status(GenServer.server()) :: map()

Get the client's current status.

stop(server)

@spec stop(GenServer.server()) :: :ok

Stop the MCP server and client.

tool_name(server_name, tool)

@spec tool_name(atom(), String.t()) :: String.t()

Build a namespaced tool name: mcp__<server>__<tool>.