legate 0.1.0

data/public/docs/guides/http_client_usage.md

@@ -0,0 +1,264 @@
+# Using the Legate HttpClient Module
+
+The `Legate::Tools::Base::HttpClient` module provides a standardized and robust way for custom Legate tools to make HTTP(S) requests. It's built on the `excon` gem, offering features like persistent connections, configurable timeouts, and middleware support (though used minimally by default).
+
+This guide explains how to integrate and use the `HttpClient` in your tools.
+
+## 1. Including and Setting Up the HttpClient
+
+To use the `HttpClient`, include the module in your tool class and call `setup_http_client` within your tool's `initialize` method.
+
+```ruby
+require 'legate/tool'
+require 'legate/tools/base/http_client' # Include the HttpClient module
+
+class MyCustomHttpTool < Legate::Tool
+  include Legate::Tools::Base::HttpClient # Include the module
+
+  tool_description 'A tool that makes HTTP calls.'
+
+  def initialize(**options)
+    super(**options)
+
+    # Setup the HTTP client
+    setup_http_client(
+      base_url: 'https://api.example.com/v1/',
+      headers: { 'X-Custom-Default-Header' => 'MyValue' },
+      options: {
+        persistent: true,
+        connect_timeout: 5, # seconds
+        read_timeout: 10,   # seconds
+        write_timeout: 10   # seconds
+      }
+    )
+  end
+
+  # ... tool methods ...
+end
+```
+
+### `setup_http_client(base_url:, headers: {}, options: {})`
+
+This method initializes and configures the underlying `Excon::Connection`.
+
+*   **`base_url:`** (String, required): The base URL for the API your tool will interact with (e.g., `https://api.example.com/v1/`). It must be a valid HTTP or HTTPS URL.
+*   **`headers:`** (Hash, optional): Default HTTP headers to be sent with every request made by this client instance. These can be overridden on a per-request basis.
+    *   A default `User-Agent` header (e.g., `Legate-Ruby/0.1.0 Excon/0.104.0`) is automatically added unless you provide your own.
+*   **`options:`** (Hash, optional): Options passed directly to `Excon.new` for configuring the connection. Common options include:
+    *   `persistent:` (Boolean): Whether to use persistent connections (default: `true`).
+    *   `connect_timeout:`, `read_timeout:`, `write_timeout:` (Numeric): Connection, read, and write timeouts in seconds (defaults: `5`, `15`, `15` respectively).
+    *   `ssl_verify_peer:` (Boolean): Whether to verify the SSL certificate (default: `true`).
+    *   `proxy:` (String): Proxy server URL.
+    *   `instrumentor:` Allows specifying a custom Excon instrumentor. By default, it uses an internal `QuietInstrumentor` (a subclass of `Excon::StandardInstrumentor`) that logs only errors, keeping normal request/response traffic out of the logs.
+
+## 2. Making HTTP Requests
+
+Once set up, you can use the provided helper methods to make HTTP requests:
+
+*   `http_get(path, query: {}, headers: {}, options: {})`
+*   `http_head(path, query: {}, headers: {}, options: {})` - Returns headers only, no body (efficient for status checks)
+*   `http_post(path, body: nil, query: {}, headers: {}, options: {})`
+*   `http_put(path, body: nil, query: {}, headers: {}, options: {})`
+*   `http_delete(path, query: {}, headers: {}, options: {})`
+
+### Common Parameters
+
+*   **`path`** (String): The path for the request.
+    *   If it's a relative path (e.g., `users`, `/users`), it will be joined with the `base_url` provided during setup.
+    *   If it's an absolute URL (e.g., `https://another.api.com/data`), that URL will be used directly for the request, and a temporary Excon client will be used with the same connection options defined in `setup_http_client`.
+*   **`query:`** (Hash, optional): A hash of query parameters to be appended to the URL (e.g., `{ sort: 'name', limit: 10 }`).
+*   **`headers:`** (Hash, optional): Headers specific to this request. These will be merged with (and can override) the default headers set in `setup_http_client`.
+*   **`options:`** (Hash, optional): Excon request options specific to this request (e.g., to override timeouts for a single long-running request).
+*   **`body:`** (Object, optional, for `http_post`, `http_put`): The request body.
+    *   If `body` is a `Hash`, it will typically be automatically encoded as a JSON string, and the `Content-Type` header will be set to `application/json; charset=utf-8` unless a `Content-Type` is explicitly provided in the `headers:` parameter for the request.
+    *   If `body` is already a `String`, it will be sent as-is. You should ensure it's correctly encoded and set the appropriate `Content-Type` header if needed.
+
+### Example: Making a GET Request
+
+```ruby
+def fetch_user_data(user_id)
+  response = http_get("users/#{user_id}", query: { include_details: true })
+  # Process the response (see "Handling Responses" below)
+  JSON.parse(response.body)
+rescue Legate::ToolHttpError => e
+  Legate.logger.error "HTTP error fetching user #{user_id}: #{e.message}, Status: #{e.response&.status}"
+  # Handle specific statuses, e.g., e.response.status == 404
+  nil
+rescue Legate::ToolError => e
+  Legate.logger.error "Tool error fetching user #{user_id}: #{e.message}"
+  nil
+end
+```
+
+### Example: Making a HEAD Request
+
+HEAD requests are useful for checking if a resource exists or getting metadata without downloading the full response body. This is efficient for status checks or verifying URLs.
+
+```ruby
+def check_url_status(url)
+  # HEAD requests work with absolute URLs too
+  response = http_head(url)
+  {
+    status_code: response.status,
+    content_type: response.headers['Content-Type'],
+    content_length: response.headers['Content-Length'],
+    reachable: (200..399).cover?(response.status)
+  }
+rescue Legate::ToolHttpError => e
+  # For a status checker, non-2xx responses may be valid results
+  # You can extract the response from the error
+  if e.response
+    { status_code: e.response.status, reachable: false }
+  else
+    { status_code: nil, reachable: false, error: e.message }
+  end
+rescue Legate::ToolNetworkError, Legate::ToolTimeoutError => e
+  { status_code: nil, reachable: false, error: e.message }
+end
+```
+
+## 3. Handling Responses
+
+The request helper methods (`http_get`, `http_head`, etc.) return an `Excon::Response` object upon a successful request (typically HTTP 2xx status codes).
+
+You can access various parts of the response:
+
+*   `response.status` (Integer): The HTTP status code.
+*   `response.body` (String): The response body. You may need to parse it (e.g., `JSON.parse(response.body)`).
+*   `response.headers` (Hash): A hash of response headers.
+
+```ruby
+response = http_get('status')
+if response.status == 200
+  Legate.logger.info "API Status: #{response.body}"
+  content_type = response.headers['Content-Type']
+  Legate.logger.info "Content-Type: #{content_type}"
+else
+  Legate.logger.warn "Unexpected status: #{response.status}"
+end
+```
+If an HTTP error status (4xx or 5xx) is returned by the server, an `Legate::ToolHttpError` will be raised (see Error Handling).
+
+## 4. Error Handling
+
+The `HttpClient` module wraps common `Excon::Error` exceptions into more specific `Legate::ToolError` subclasses. This provides a consistent error handling experience for tools.
+
+Always include `begin...rescue` blocks when making HTTP calls.
+
+*   **`Legate::ToolTimeoutError`**: Raised for request timeouts (corresponds to `Excon::Error::Timeout`).
+*   **`Legate::ToolNetworkError`**: Raised for socket or underlying network issues (corresponds to `Excon::Error::Socket`).
+*   **`Legate::ToolCertificateError`**: Raised for SSL certificate errors (corresponds to `Excon::Error::CertificateError`).
+*   **`Legate::ToolHttpError`**: Raised for HTTP status codes in the 4xx and 5xx ranges (corresponds to `Excon::Error::HTTPStatusError`).
+    *   You can access the `Excon::Response` object via `e.response` on this error (e.g., `e.response.status`, `e.response.body`).
+*   **`Legate::ToolError`**: A general error class used for other Excon errors or issues within the HttpClient module itself (e.g., failed JSON encoding, invalid base URL).
+
+When an `Legate::ToolError` is raised due to an underlying `Excon::Error`, the original Excon error is preserved in the `cause` attribute of the Legate error. This is useful for debugging.
+
+```ruby
+begin
+  response = http_post('submit_data', body: { key: 'value' })
+  # ... process response ...
+rescue Legate::ToolTimeoutError => e
+  Legate.logger.error "Request timed out: #{e.message}"
+  # Optionally inspect e.cause if needed
+rescue Legate::ToolHttpError => e
+  Legate.logger.error "HTTP Error: #{e.message} (Status: #{e.response&.status})"
+  if e.response&.status == 401
+    Legate.logger.warn "Authentication required or token expired."
+    # Potentially trigger re-authentication logic
+  end
+  Legate.logger.debug "Response body from error: #{e.response&.body}"
+rescue Legate::ToolNetworkError => e
+  Legate.logger.error "Network error: #{e.message}"
+rescue Legate::ToolError => e # Catch-all for other HttpClient or generic Legate tool errors
+  Legate.logger.error "A tool error occurred: #{e.message}"
+  Legate.logger.debug "Original cause: #{e.cause.inspect}" if e.cause
+end
+```
+
+## 5. Authentication
+
+The `HttpClient` module itself is unopinionated about authentication mechanisms. It **does not** manage authentication state (like tokens) or complex authentication flows (like OAuth2).
+
+Your tool is responsible for:
+1.  Determining the required authentication method (e.g., API key, Bearer token).
+2.  Retrieving the necessary credentials. This might come from the tool's configuration, the `ToolContext` (session state, possibly using the Legate's credential management features), or an interactive flow.
+3.  Injecting the credentials into the HTTP request, typically via the `headers:` parameter of the request helper methods.
+
+### Example: Bearer Token Authentication
+
+```ruby
+# Assume 'token' is retrieved by the tool
+auth_headers = { 'Authorization' => "Bearer #{token}" }
+response = http_get('/protected/resource', headers: auth_headers)
+```
+
+### Example: API Key in Header
+
+```ruby
+# Assume 'api_key' is retrieved by the tool
+auth_headers = { 'X-Api-Key' => api_key }
+response = http_get('/data', headers: auth_headers)
+```
+
+Refer to the Legate's authentication documentation for details on managing and retrieving credentials within tools.
+
+## 6. Full Example
+
+Here's a simple tool that fetches a random cat fact using the `HttpClient`.
+
+```ruby
+require 'legate/tool'
+require 'legate/tools/base/http_client'
+require 'json'
+
+module Legate
+  module Tools
+    # Tool name :cat_fact_tool is inferred from the class name.
+    class CatFactTool < Legate::Tool
+      include Legate::Tools::Base::HttpClient
+
+      tool_description 'Fetches a random cat fact.'
+      # No parameters needed for this tool.
+
+      def initialize(**options)
+        super(**options)
+        setup_http_client(
+          base_url: 'https://catfact.ninja/',
+          options: { read_timeout: 5 } # Short timeout for this API
+        )
+      end
+
+      private
+
+      # perform_execution takes two positional args (params, context) and must
+      # return a status Hash: { status: :success, result: ... } or
+      # { status: :error, error_message: ... }.
+      def perform_execution(_params, _context)
+        Legate.logger.info 'Fetching a cat fact...'
+        response = http_get('fact') # Path is relative to base_url
+        parsed_body = JSON.parse(response.body)
+        fact = parsed_body['fact']
+        Legate.logger.info "Retrieved cat fact: #{fact}"
+        { status: :success, result: fact }
+      rescue Legate::ToolHttpError => e
+        Legate.logger.error "HTTP error fetching cat fact: #{e.message}, Status: #{e.response&.status}"
+        { status: :error, error_message: "HTTP #{e.response&.status} - #{e.message}" }
+      rescue Legate::ToolTimeoutError => e
+        Legate.logger.error "Timeout fetching cat fact: #{e.message}"
+        { status: :error, error_message: 'Request timed out.' }
+      rescue Legate::ToolError => e
+        Legate.logger.error "Tool error fetching cat fact: #{e.message}"
+        { status: :error, error_message: e.message }
+      rescue JSON::ParserError => e
+        Legate.logger.error "Failed to parse cat fact response: #{e.message}"
+        { status: :error, error_message: 'Could not parse response from cat fact API.' }
+      end
+    end
+  end
+end
+```
+
+> **Note:** Rather than returning the result hash, a tool may also raise a `Legate::ToolError` subclass (e.g., on a failed HTTP request) and let the Legate runtime convert it into a standard error event. The built-in `Legate::Tools::CatFacts` tool uses that approach.
+
+This guide should help you effectively use the `Legate::Tools::Base::HttpClient` module to build powerful, network-enabled tools within the Legate framework. 

data/public/docs/guides/llm_providers.md

@@ -0,0 +1,137 @@
+# LLM Providers
+
+Legate's planner talks to a Large Language Model through a small, pluggable adapter interface (`Legate::LLM::Adapter`). **Gemini is the default**, but you can point Legate at any provider — a hosted API, a local model, or your own implementation — without changing your agents.
+
+## The adapter interface
+
+An adapter is any object that responds to three methods:
+
+```ruby
+class MyAdapter < Legate::LLM::Adapter
+  # Whether the adapter can make calls (e.g. an API key is present).
+  def available?; true; end
+
+  # The resolved model id, or nil if unavailable.
+  def model_name; 'my-model'; end
+
+  # Generate a completion for a single prompt.
+  # @param prompt [String]
+  # @param json [Boolean] request raw-JSON output where the provider supports it
+  # @return [String, nil] the model's text output (nil if unavailable)
+  def generate(prompt, json: false)
+    # ... call your provider, return the text ...
+  end
+end
+```
+
+The planner calls `generate(prompt, json: true)` and parses a JSON plan out of the returned text, so any provider that can return text (ideally JSON-constrained) works. An adapter can additionally implement `supports_structured_output?` + accept a `schema:` to **guarantee** valid plan JSON via the provider's native structured output — `Legate::LLM::Gemini` does this (Gemini `responseSchema`), so plans on Gemini are schema-constrained rather than parsed out of prose.
+
+## Built-in adapters
+
+### Gemini (default)
+
+Used automatically when no other provider is configured. Requires `GOOGLE_API_KEY` (or `GEMINI_API_KEY`).
+
+```ruby
+Legate::LLM::Gemini.new(model: 'gemini-3.5-flash', api_key: ENV['GOOGLE_API_KEY'])
+```
+
+### Ollama (local)
+
+Talks to a local [Ollama](https://ollama.com) server over HTTP — **no API key, no cost, fully local**. Configure the host with the `:host` option or the `OLLAMA_HOST` env var (default `http://localhost:11434`).
+
+```ruby
+Legate::LLM::Ollama.new(model: 'llama3')               # http://localhost:11434
+Legate::LLM::Ollama.new(model: 'qwen2.5', host: 'http://gpu-box:11434', read_timeout: 180)
+```
+
+It requests JSON-constrained output (Ollama's `"format": "json"`) when the planner asks for a plan.
+
+## Selecting a provider for every agent
+
+Set a factory once at boot. It receives `model:`, `api_key:`, and `logger:` keyword arguments and returns an adapter:
+
+```ruby
+# Use a local Ollama model everywhere instead of Gemini
+Legate::LLM.default_adapter_factory = lambda do |model:, **|
+  Legate::LLM::Ollama.new(model: model)
+end
+```
+
+When unset (the default), Legate uses the Gemini adapter. The per-agent `model_name` is passed through to your factory as `model:`, so you can still vary the model per agent.
+
+## Overriding for a single planner
+
+If you construct a planner directly, you can inject an adapter for just that instance (this takes precedence over the global factory):
+
+```ruby
+adapter = Legate::LLM::Ollama.new(model: 'llama3')
+planner = Legate::Planner.new(agent: my_agent, llm_adapter: adapter)
+```
+
+> Most users won't construct planners by hand — agents build their own. The `default_adapter_factory` above is the usual way to choose a provider.
+
+## Writing a custom adapter
+
+To support a provider Legate doesn't ship (OpenAI, Anthropic, a gateway, a mock for tests), implement the three interface methods and wire it through the factory:
+
+```ruby
+class OpenAIAdapter < Legate::LLM::Adapter
+  def initialize(model:, api_key: ENV['OPENAI_API_KEY'], logger: nil, **)
+    @model = model
+    @api_key = api_key
+    @logger = logger || Legate.logger
+  end
+
+  def available?
+    !@api_key.to_s.empty?
+  end
+
+  def model_name
+    available? ? @model : nil
+  end
+
+  def generate(prompt, json: false)
+    # POST to your provider, return the assistant's text.
+    # Pass a JSON-mode / response-format flag when json is true.
+  end
+end
+
+Legate::LLM.default_adapter_factory = lambda do |model:, **|
+  OpenAIAdapter.new(model: model)
+end
+```
+
+That's the whole contract — `available?`, `model_name`, `generate(prompt, json:)`.
+
+## Optional: native function calling
+
+[Agentic (`:react`) agents](agentic_agents) pick their next action one step at a
+time. By default the planner does this by prompting for a JSON action and parsing
+it — works with any adapter. An adapter can opt into the provider's **native
+tool-calling API** instead (more reliable: the tool name and arguments come back
+typed, not parsed out of prose) by implementing two more methods:
+
+```ruby
+def supports_function_calling?
+  true
+end
+
+# @param tools [Array<Hash>] each { name:, description:, parameters: <JSON Schema> }
+# @return [Hash] { kind: :tool, name:, arguments:, thought: } or { kind: :final, text:, thought: }
+def generate_with_tools(prompt, tools:)
+  # Call your provider's function-calling endpoint with the tool schemas,
+  # then return the structured choice in the neutral shape above.
+end
+```
+
+`Legate::LLM::Gemini` implements both, so agentic agents on Gemini use native
+function calling automatically. Adapters that don't (Ollama, the default custom
+adapter) inherit `supports_function_calling? => false` and stay on the JSON path —
+no action needed. This affects only the agentic next-action decision; the
+multi-step planner still uses `generate`.
+
+## See also
+
+- [Agentic Agents](agentic_agents) — the ReAct loop these adapters reason through.
+- [Legate Planner](../core_concepts/legate_planner) — how the planner turns a model response into an executable plan.

data/public/docs/guides/mcp_client_integration.md

@@ -0,0 +1,232 @@
+# Using Legate as an MCP Client
+
+This guide explains how to configure and use an `Legate::Agent` to connect to external Model Context Protocol (MCP) servers and utilize the tools they provide. This allows your Legate agents to leverage a wider ecosystem of capabilities beyond their natively defined tools.
+
+## Architecture Overview: Legate as MCP Client
+
+The following diagram illustrates how an Legate Agent interacts with an external MCP server:
+
+```mermaid
+graph LR
+    subgraph Legate Agent Process
+        A[Legate::Agent]
+        Client[Legate::Mcp::Client]
+        Conn["Legate::Mcp::Connection::Stdio / ::Sse"]
+        WrapperTool["Legate::Mcp::ToolWrapper"]
+        Planner[Legate::Planner]
+
+        A -- Configures & Manages --> Client
+        Client -- Uses --> Conn
+        Planner -- Considers --> WrapperTool
+        A -- Executes --> WrapperTool
+        WrapperTool -- Delegates Call --> Client
+    end
+
+    subgraph External MCP Server Process
+        MCP_Srv[External MCP Server]
+        MCP_Tool[Actual External Tool]
+    end
+
+    Conn -- JSON-RPC --> MCP_Srv
+    MCP_Srv -- Executes --> MCP_Tool
+    MCP_Srv -- JSON-RPC Response --> Conn
+
+    style A fill:#ccf,stroke:#333,stroke-width:2px
+    style Client fill:#ccf,stroke:#333,stroke-width:2px
+    style WrapperTool fill:#ccf,stroke:#333,stroke-width:2px
+    style MCP_Srv fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+**Key Components:**
+
+*   **`Legate::Agent`:** The main Legate agent instance.
+*   **`Legate::Mcp::Client`:** Manages the connection and communication with a specific MCP server.
+*   **`Legate::Mcp::Connection::Stdio` / `Legate::Mcp::Connection::Sse`:** Handle the low-level transport (STDIO or SSE). The `Legate::Mcp::ConnectionManager` owns the connection lifecycle (connecting, discovering tools, and disconnecting).
+*   **`Legate::Mcp::ToolWrapper`:** A dynamically created proxy `Legate::Tool` that represents an external MCP tool within the Legate agent.
+*   **External MCP Server:** The third-party server providing tools via MCP.
+
+## 1. Configuration
+
+> ### ⚠️ Security: MCP server configs are trusted input
+>
+> Connecting to an MCP server means **running code you trust**, exactly like adding a dependency to your project:
+>
+> - **`:stdio` servers launch a local subprocess** from the configured `command`/`args`. Whoever can set an agent's `mcp_servers` can run arbitrary local commands — that's the whole point of stdio MCP, not a flaw. Treat an MCP config like a `Gemfile` entry.
+> - **`:sse`/remote servers are *not* SSRF-restricted.** MCP servers legitimately run on `localhost` or inside your private network, so Legate does **not** block private/loopback/metadata addresses for MCP URLs (unlike the outbound webhook tool, which does). A malicious MCP URL could reach internal services.
+>
+> The trust boundary is therefore **who can supply an agent definition's `mcp_servers`**. In code you control this is a non-issue. If you let *untrusted users* create or edit agent definitions (e.g. by exposing the bundled web UI on a public network), they can run commands and reach internal hosts on your server. **Do not expose the web UI to untrusted networks** (see the README's "Security model" section), and only configure MCP servers you would be comfortable adding as a dependency.
+
+To enable an agent to act as an MCP client, you configure it with details of the MCP servers it should connect to.
+
+### 1.1. `mcp_servers` on the Agent Definition
+
+MCP server connections are configured on the agent's `Legate::AgentDefinition` via the `mcp_servers` DSL method. Build the definition, then pass it to `Legate::Agent.new(definition:)`:
+
+```ruby
+require 'legate'
+require 'legate/mcp' # Ensure MCP modules are loaded
+
+# Example: Configuration for an MCP server running via STDIO
+stdio_server_config = {
+  type: :stdio,  # or "stdio"
+  command: 'npx', # The command to run the server
+  args: ['@modelcontextprotocol/server-filesystem', '--stdio', '/path/to/accessible/directory']
+}
+
+# Example: Configuration for an MCP server via SSE (HTTP Server-Sent Events)
+sse_server_config = {
+  type: :sse, # or "sse"
+  url: 'http://localhost:9292/mcp', # Base URL for the MCP server (SSE endpoint often /sse, messages often /messages)
+  # Optional: token: 'your-auth-token' # If the server requires bearer token authentication
+}
+
+mcp_client_definition = Legate::AgentDefinition.new.define do |a|
+  a.name :mcp_client_agent
+  a.description 'An agent that uses external MCP tools.'
+  a.instruction 'Use native and external MCP tools to help the user.'
+
+  a.use_tool :my_native_tool          # Optional: native Legate tools
+  a.use_tool :read_file               # Selected MCP tool (see section 1.2)
+  a.use_tool :list_directory          # Selected MCP tool (see section 1.2)
+
+  # Array of MCP server configs (or pass them as separate arguments)
+  a.mcp_servers stdio_server_config, sse_server_config
+end
+
+my_agent = Legate::Agent.new(definition: mcp_client_definition)
+```
+
+**Each server configuration hash requires:**
+
+*   `type`: Symbol or String. `:stdio` or `:sse`.
+*   **For `:stdio`:**
+    *   `command`: String. The executable to run the server (e.g., `npx`, `python`, `bundle exec ruby`).
+    *   `args`: Array of Strings. Arguments for the command.
+*   **For `:sse`:**
+    *   `url`: String. The base URL of the MCP server. The client will attempt to connect to standard MCP sub-paths like `/sse` for events and `/messages` for calls.
+    *   `token` (Optional): String. A bearer token for authentication if the server requires it.
+
+### 1.2. Selecting MCP Tools with `use_tool` (Crucial for V1)
+
+Due to the dynamic nature of tool discovery and potential for naming conflicts or overwhelming numbers of tools, **it is currently essential to specify which tools from the MCP server(s) the agent should actually register and use.**
+
+You do this with the same `a.use_tool :tool_name` DSL you use for native tools. When the agent starts, the `Legate::Mcp::ConnectionManager` discovers the server's tools and only registers those whose names match a `use_tool` selection:
+
+```ruby
+definition = Legate::AgentDefinition.new.define do |a|
+  a.name :mcp_client_agent
+  a.instruction '...'
+  a.mcp_servers some_mcp_server_config
+  a.use_tool :tool_name_from_mcp_server1
+  a.use_tool :another_tool_from_mcp_server2
+end
+```
+
+*   `use_tool` takes a Symbol; call it once per tool.
+*   These names **must exactly match** the tool names as exposed by the MCP server. You might need to inspect the MCP server's `tools/list` response or its documentation to get the correct names.
+*   If none of the agent's selected tool names match a server's tools, the agent will connect to the MCP server and perform the handshake but **will not register any tools** from that server.
+*   The Legate planner will only "see" and be able to use MCP tools that were selected via `use_tool` and successfully registered.
+
+## 2. How it Works
+
+1.  **Agent Initialization (`Legate::Agent.new(definition:)`)**:
+    *   The `mcp_servers` configurations are read from the definition.
+2.  **Agent Start (`agent.start`)**:
+    *   The agent's `Legate::Mcp::ConnectionManager` processes each configuration in the definition's `mcp_servers`:
+        *   A connection is established using the specified `type` (`Legate::Mcp::Connection::Stdio` or `Legate::Mcp::Connection::Sse`). This includes the MCP `initialize` handshake.
+        *   If the connection is successful, the manager calls `tools/list` on the MCP server.
+        *   For each tool schema received from the server whose name matches one of the agent's `use_tool` selections:
+            *   `Legate::Mcp::ToolWrapper.from_mcp_schema` is called. This method:
+                *   Converts the MCP tool's JSON Schema (for `inputSchema`) into the Legate parameter format. (See [Schema Conversion Details](../advanced/mcp_schema_conversion))
+                *   Dynamically creates an anonymous `Legate::Tool` subclass that acts as a proxy.
+                *   Registers this proxy tool with the agent's specific `ToolRegistry`.
+    *   The agent is now aware of both its native tools and the selected, wrapped MCP tools.
+3.  **Planning (`agent.run_task`)**:
+    *   The `Legate::Planner` considers all tools available in the agent's `ToolRegistry`, including the wrapped MCP tools.
+4.  **Execution**:
+    *   If the planner selects a wrapped MCP tool:
+        *   The agent calls the wrapper tool's `execute` method.
+        *   The `ToolWrapper` instance, in its `perform_execution` method:
+            *   Translates the Legate parameters into the JSON structure expected by the external tool.
+            *   Uses its associated `Legate::Mcp::Client` instance to send a `tools/call` request to the MCP server.
+            *   Receives the response from the MCP server.
+            *   Maps the MCP result or error back into the standard Legate status hash (e.g., `{status: :success, result: ...}` or `{status: :error, error_details: ...}`).
+5.  **Agent Stop (`agent.stop`)**:
+    *   The agent calls `disconnect` on all active `Legate::Mcp::Client` instances, terminating connections (e.g., stopping STDIO processes, closing SSE connections).
+
+## 3. Error Handling
+
+*   **Connection Errors**: If an `Legate::Mcp::Client` fails to connect during `agent.start` (e.g., STDIO command not found, SSE server unreachable, MCP handshake fails), an error is logged. That specific MCP server and its tools will be unavailable to the agent. The agent will typically continue starting with its native tools and any other successfully connected MCP servers.
+*   **Tool Execution Errors**:
+    *   **Communication Errors (`Legate::Mcp::ConnectionError`, `Legate::Mcp::ProtocolError`)**: These indicate issues with the communication channel or MCP protocol itself (e.g., invalid JSON-RPC, timeout). The `ToolWrapper` catches these and returns an Legate `:error` status hash (e.g., `{status: :error, error_message: "MCP Communication Error: ...", error_details: {mcp_error_type: 'ConnectionError'}}`).
+    *   **Remote Tool Errors (`Legate::Mcp::RemoteToolError`)**: These occur if the external MCP server successfully executed the tool, but the tool *itself* reported an error (e.g., via an MCP error object in the `tools/call` response). The `ToolWrapper` converts this into an Legate `:error` status hash, often including the original error message, code, and data from the MCP server in the `error_details` field.
+*   **Agent Behavior**: If a plan step involving an external MCP tool fails, the agent's plan execution typically halts, and the final agent response will reflect the error status hash, similar to failures with native tools.
+
+## 4. Example Snippet
+
+```ruby
+# (Ensure Legate.configure and MCP server setup as per above)
+
+# Define a native tool for comparison.
+# The tool name :native_tool is inferred from the class name.
+class NativeTool < Legate::Tool
+  tool_description 'A simple native tool.'
+
+  private
+
+  def perform_execution(_params, _context)
+    { status: :success, result: 'Native tool executed!' }
+  end
+end
+Legate::GlobalToolManager.register_tool(NativeTool)
+
+# Configure the MCP server (e.g., filesystem server)
+# Ensure '/tmp/mcp_test_dir' exists and is accessible by the npx command.
+# Create a file: echo "Hello from MCP!" > /tmp/mcp_test_dir/test.txt
+mcp_server_config = {
+  type: :stdio,
+  command: 'npx',
+  args: ['@modelcontextprotocol/server-filesystem', '--stdio', '/tmp/mcp_test_dir']
+}
+
+definition = Legate::AgentDefinition.new.define do |a|
+  a.name :mcp_client_agent
+  a.instruction 'Use native and filesystem tools to help the user.'
+  a.use_tool :native_tool
+  a.use_tool :read_file # Assuming server-filesystem exposes 'read_file'
+  a.mcp_servers mcp_server_config
+end
+
+agent = Legate::Agent.new(definition: definition)
+
+agent.start
+
+Legate.logger.info("Agent Tools Available: #{agent.available_tools_metadata.map { |t| t[:name] }}")
+
+# Example task
+session_service = Legate::SessionService::InMemory.new
+session_id = session_service.create_session(app_name: agent.name, user_id: 'test').id
+
+# This prompt assumes the LLM/planner knows to use 'read_file' for such a request
+user_input = "Can you read the file named 'test.txt' for me?"
+
+final_event = agent.run_task(
+  session_id: session_id,
+  user_input: user_input,
+  session_service: session_service
+)
+
+Legate.logger.info("Agent Task Result: #{final_event.content.inspect}")
+
+agent.stop
+```
+*For a more complete, runnable example, see `examples/14_mcp_client.rb` in the `legate` repository.*
+
+## 5. Security Considerations
+
+*   **STDIO Connections**: Assume a trusted local environment. The commands specified are executed on the system where `legate` is running.
+*   **SSE Connections**:
+    *   Use HTTPS (`https://...`) for the MCP server URL in production to protect data in transit.
+    *   If the server requires authentication, provide the token via the `token` parameter in the SSE configuration. Manage this token securely.
+*   **Trust**: By configuring an agent to connect to an MCP server, you are trusting that server and the tools it exposes. Be cautious about connecting to untrusted MCP servers, as they can execute code or access resources based on the tools they provide.
+*   **Selected Tools**: The `use_tool` selection mechanism provides a layer of control, ensuring that only explicitly approved tools from an MCP server are made available to the agent.