class LittleGhost::MCP::Toolset

Connects one MCP server to an Agent as a reusable Tool provider. Each Agent run gets its own connection. map_tool chooses and configures the generated Tool classes; map_result converts results that need application-specific handling.

class HelpCenterTools < LittleGhost::MCP::Toolset
  connection url: "https://mcp.example/rpc", timeout: 20
end

class CustomerSupportAgent < LittleGhost::Agent
  tools HelpCenterTools
end

Public Class Methods

connection() → Hash, Proc, nil

connection(values) → Hash

connection { |binding| ... } → Proc

Source

# File lib/little_ghost/mcp/toolset.rb, line 48
def connection(value = UNSET, &resolver)
  return connection_value if value.equal?(UNSET) && !resolver
  raise ArgumentError, "provide a connection or a block, not both" unless value.equal?(UNSET) || !resolver

  configured = resolver || value
  unless configured.is_a?(Hash) || configured.respond_to?(:call)
    raise ArgumentError, "connection must be a hash or callable"
  end

  self.connection_value = configured.is_a?(Hash) ? normalize_connection(configured) : configured
end

Declares a static connection Hash or a block called with the current Tool::Binding. The Hash requires url and may include headers, timeout, signer, allow_insecure_http, and max_response_bytes.

map_result() → Proc, nil

map_result { |result, call:, binding:| ... } → Proc

Source

# File lib/little_ghost/mcp/toolset.rb, line 80
def map_result(&mapping)
  return result_mapping_value unless mapping

  self.result_mapping_value = mapping
end

Maps each immutable MCP::Result. The block receives call: and binding: keywords and returns any Ruby value or Tool::Result.

map_tool() → Proc, nil

map_tool { |tool_class, definition:, binding:| ... } → Proc

Source

# File lib/little_ghost/mcp/toolset.rb, line 68
def map_tool(&mapping)
  return tool_mapping_value unless mapping

  self.tool_mapping_value = mapping
end

Maps each generated Tool class. The block receives definition: and binding: keywords. Return the configured Tool class, or nil to omit it. Changing Tool#tool_name does not change the operation name sent to the MCP server.

on_error() → Proc, nil

on_error { |error, binding:| ... } → Proc

Source

# File lib/little_ghost/mcp/toolset.rb, line 105
def on_error(&callback)
  return error_callback_value unless callback

  self.error_callback_value = callback
end

Observes an expected discovery failure caught by optional true. Exceptions raised by this callback propagate.

optional() → true or false

optional(value) → true or false

Source

# File lib/little_ghost/mcp/toolset.rb, line 93
def optional(value = UNSET)
  return optional_value if value.equal?(UNSET)

  self.optional_value = !!value
end

Makes expected provider and protocol discovery failures produce no tools. Configuration, cancellation, deadline, and callback failures still propagate.

tools (binding)

Source

# File lib/little_ghost/mcp/toolset.rb, line 112
def tools(binding)
  options = resolved_connection(binding)
  context = binding.run&.context
  mapper = tool_mapping_value
  result_mapper = result_mapping_value
  options = connection_with_wrapped_signer(options)
  Instrumentation.instrument(:mcp_discovery, toolset: toolset_name) do |telemetry|
    client = Client.new(
      transport: HTTPTransport.new(**options),
      name: toolset_name,
      tool_mapper: mapper && lambda do |tool_class, definition:, binding:|
        invoke_application_callback do
          mapper.call(tool_class, definition:, binding:)
        end
      end,
      result_mapper: result_mapper && lambda do |result, call:, binding:|
        result_mapper.call(result, call:, binding:)
      end
    )
    discovered = client.tools(context:, binding:)
    telemetry[:outcome] = :success
    telemetry[:tool_count] = discovered.length
    discovered
  end
rescue CallbackFailure => error
  raise error.original
rescue ProviderError, ProtocolError, ToolError => error
  raise unless optional_value

  error_callback_value&.call(error, binding:)
  []
end

Generates Tool classes for an Agent’s current binding.