class LittleGhost::MCP::Client

Client makes tools from an MCP server available as ordinary LittleGhost tools. Agents can use a remote capability without learning a second tool interface.

transport = LittleGhost::MCP::HTTPTransport.new(url: "https://mcp.example/rpc")
client = LittleGhost::MCP::Client.new(transport:, prefix: "docs")
client.tools.map(&:tool_name) # => ["docs_search", "docs_fetch"]

Tool names are normalized and checked for collisions. Pagination, tool count, and response sizes are limited; rejected_tools and definition_filter can enforce an application allowlist.

Server definitions and results remain untrusted input. LittleGhost validates them before creating tools, but applications still decide which servers and capabilities an agent may use.

A client and its transport represent one authenticated server session. Create a separate pair for each principal or trust boundary. Protocol initialization and subsequent requests through one client are serialized; do not share its transport with another client.

Public Class Methods

new (transport:, name: "mcp", prefix: nil, rejected_tools: [], definition_filter: nil, max_tools: DEFAULT_MAX_TOOLS, max_pages: DEFAULT_MAX_PAGES)

Source

# File lib/little_ghost/mcp/client.rb, line 173
def initialize(
  transport:,
  name: "mcp",
  prefix: nil,
  rejected_tools: [],
  definition_filter: nil,
  max_tools: DEFAULT_MAX_TOOLS,
  max_pages: DEFAULT_MAX_PAGES
)
  if definition_filter && !definition_filter.respond_to?(:call)
    raise ArgumentError, "definition_filter must respond to call"
  end

  @transport = transport
  @name = String(name)
  @prefix = prefix&.to_s
  @rejected_tools = rejected_tools.map(&:to_s).freeze
  @definition_filter = definition_filter
  @max_tools = positive_integer(max_tools, :max_tools)
  @max_pages = positive_integer(max_pages, :max_pages)
  @request_id = 0
  @mutex = Mutex.new
  @initialization_mutex = Mutex.new
  @source_names_mutex = Mutex.new
  @source_names = {}
  @initialized = false
end

Uses a transport that responds to send.

Public Instance Methods

call (name, arguments, context: nil)

Source

# File lib/little_ghost/mcp/client.rb, line 219
def call(name, arguments, context: nil)
  source_name = @source_names_mutex.synchronize { @source_names.fetch(name.to_s, name.to_s) }
  result = request("tools/call", {name: source_name, arguments: arguments}, context:)
  content = serialize_result(result)
  raise ToolError, content if result["isError"]

  content
end

Calls an exposed tool and produces text or serialized structured content. Server-declared errors raise ToolError.

tools (context: nil)

Source

# File lib/little_ghost/mcp/client.rb, line 203
def tools(context: nil)
  @initialization_mutex.synchronize do
    initialize_protocol(context:) unless @initialized
  end
  definitions = list_tool_definitions(context:)
  definitions.filter_map do |definition|
    source_name = definition_name(definition)
    next if @rejected_tools.include?(source_name)
    next if @definition_filter && !@definition_filter.call(definition)

    build_tool(definition)
  end
end

Negotiates the protocol when needed, then provides Tool instances for the server’s current definitions.