little_ghost 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d214ff7dd49c056712968000f9ddc127bc132dd4b97b8f0c89bb3adb2f52f3b0
-  data.tar.gz: de2f85339390969db2ae0863bf9056ab386b07e2bf05cc976f23899ae2b318d2
+  metadata.gz: d24d2ed91efec3898453d20dfea0902edfca7c207fac0983426153208b308a1e
+  data.tar.gz: 74aefcfaf1d9113640f80c6a7c4462c1e4919265705f0eb37c82c9f694eabcae
 SHA512:
-  metadata.gz: 48004e9b2b4c826877601f31681129f5f0434f544aa979941d2d09840ca677ccbf86e0334cdd9de60081601e039326d445a033064940049dbd3f5e27243f47ac
-  data.tar.gz: 88fc87d32cb553b047273e249685f410ff8721e32275a3f3800e00cd79a674fb43188b0ef34d2b0a2ca04c4502a18503a6da791d2634ec92f4bc539d665ad36a
+  metadata.gz: de9e90761042a5cad938664be479e6d35d6b0423b213cde3ac05f0a033c4de7468ef96252073b1405a73510c53b650ea5d7c74be2cae9bd68922494a05cfb406
+  data.tar.gz: 96ac0a88302659cad84e80c4491c23ab4bad211b0db8fe9a1bb370dbbcb0a2090d81cc3c922cc62d18ace4804a559efba5bbcb6ee44a6d52cec58ad5f45dfcc0

data/README.md

@@ -20,7 +20,9 @@ run.response
 # One possible response: Hi! How can I help today?
 ```
 
-That small definition is already a complete agent. LittleGhost makes the model call, tracks usage, supports streaming, and closes the resources it creates for the request. Add a tool when the agent needs something from your application. Bring in more agents when the work grows.
+That definition is a complete Agent. LittleGhost makes the model call, tracks
+usage, supports streaming, and closes request resources. Add a Tool for
+application capabilities or an Assembly as the work grows.
 
 Model requests may send system instructions, caller input, conversation history,
 Tool results, and attachments to the selected provider. Model wording can vary
@@ -40,9 +42,33 @@ $ bundle install
 $ export OPENROUTER_API_KEY="..."
 ```
 
-OpenRouter keeps the first setup to one credential. It is not required: LittleGhost also includes adapters for OpenAI-compatible APIs, Anthropic, Gemini, Vertex AI, and Bedrock. [Running in Production](docs/guides/production.md) shows how to configure providers and give model choices application-facing names.
+The introductory guides use OpenRouter so you can start with one key. Prefer
+another hosted provider or a local Ollama or LM Studio server? See [Provider
+Support](docs/guides/providers.md).
 
-LittleGhost runs inside your Ruby process. Use it from a controller, job, CLI, or service. If you want a conventional layout, start with `app/agents`, `app/assemblies`, `app/prompts`, and `app/tools`.
+LittleGhost runs inside your Ruby process. Use it from a controller, job, CLI,
+or service.
+
+## Generate a small application
+
+Generate a conventional standalone application:
+
+```sh
+$ gem install little_ghost
+$ little_ghost new MyApp
+$ cd my_app
+$ export OPENROUTER_API_KEY="..."
+$ bin/little_ghost console
+```
+
+The generator installs the bundle. `bin/little_ghost console` runs that
+bundle's LittleGhost version and loads the application before starting IRB.
+
+The source checkout also includes a complete
+[single-file Agent](https://github.com/littleghostai/little_ghost/tree/main/examples/basic_agent)
+and
+[coding harness](https://github.com/littleghostai/little_ghost/tree/main/examples/coding_harness),
+both configured for local Ollama.
 
 ## Give an agent real capabilities
 
@@ -120,15 +146,17 @@ upgrading, because interfaces may change between releases.
 
 - [Getting Started](docs/guides/getting_started.md) takes you from installation to a tool-backed, streaming agent.
 - [Core Concepts](docs/guides/core_concepts.md) builds the mental model from Agent to Assembly.
-- [Models and Providers](docs/guides/models_and_providers.md) gives shared model choices application-facing names.
+- [Models and Providers](docs/guides/models_and_providers.md) explains targets, shared roles, and per-request model selection.
+- [Provider Support](docs/guides/providers.md) has copyable setup for hosted APIs and local model servers.
 - [Prompts as Views](docs/guides/prompt_views.md) gives growing instructions, shared pieces, and application values a natural home.
 - [Tools](docs/guides/tools.md) explains how models call focused Ruby operations.
+- [MCP](docs/guides/mcp.md) connects agents to operations published through the Model Context Protocol.
 - [Structured Results and Content](docs/guides/structured_outputs_and_content.md) covers checked result shapes, images, and documents.
 - [Compose Agents](docs/guides/assemblies.md) walks through workflows, swarms, graphs, nesting, and builders.
 - [Skills](docs/guides/skills.md) organizes reusable instructions and supporting resources.
 - [Workspaces and Sandboxes](docs/guides/sandboxing.md) gives files and child processes a deliberate place to run.
 - [Code Mode](docs/guides/code_mode.md) lets a model compose Tools in sandboxed Ruby or optional JavaScript.
-- [Integrations](docs/guides/integrations.md) connects MCP, AG-UI, and OpenTelemetry.
+- [Integrations](docs/guides/integrations.md) connects Run streams to AG-UI and OpenTelemetry.
 - [Running in Production](docs/guides/production.md) covers configuration, saved conversations, supervision, and observability.
 - [API reference](rdoc-ref:LittleGhost) provides exact method signatures and ownership rules.
 

data/docs/guides/code_mode.md

@@ -274,5 +274,5 @@ engine, but the generated program then has the same host access as the parent.
 
 See `LittleGhost::CodeMode::Engine`, `LittleGhost::CodeMode::Session`, and
 `LittleGhost::CodeMode::ProgramResult` for the extension contract. Continue
-with [Integrations](integrations.md) to connect Runs to MCP tools, AG-UI, and
-OpenTelemetry.
+with [MCP](mcp.md) to add operations from a remote server, or
+[Integrations](integrations.md) to connect Runs to AG-UI and OpenTelemetry.

data/docs/guides/getting_started.md

@@ -17,7 +17,8 @@ $ export OPENROUTER_API_KEY="..."
 
 Use your application's secret manager outside a local shell, and never commit provider credentials.
 
-This guide uses OpenRouter because one credential is enough to begin. LittleGhost can use other provider connections too; you will configure those in [Running in Production](production.md).
+This guide uses OpenRouter to keep setup to one key. Prefer another hosted
+provider or a local model server? Start with [Provider Support](providers.md).
 
 ## See your first answer
 
@@ -201,6 +202,30 @@ app/
     └── help_center_lookup_tool.rb
 ```
 
+To generate this layout for a standalone application, install the gem and run
+`little_ghost new`:
+
+```sh
+$ gem install little_ghost
+$ little_ghost new MyApp
+$ cd my_app
+$ export OPENROUTER_API_KEY="..."
+$ bin/little_ghost console
+```
+
+The generator creates `my_app` with one Agent, a prompt view, configuration,
+the conventional application directories, an installed bundle, and a local
+LittleGhost command. `bin/little_ghost console` uses the generated
+application's bundle, loads its configuration and classes, and then starts
+IRB.
+
+The source repository also contains a complete
+[single-file Agent](https://github.com/littleghostai/little_ghost/tree/main/examples/basic_agent)
+and a
+[coding harness](https://github.com/littleghostai/little_ghost/tree/main/examples/coding_harness)
+that demonstrates Agents, prompt views, Tools, a Graph, a Workspace, and a
+native Sandbox.
+
 You now have the smallest useful LittleGhost application: one Agent, one Tool, and one familiar Ruby call.
 
 When the feature grows, the calling style stays the same. An **assembly** lets one or more agents work as a unit while keeping `.ask` and `.stream_ask`. Read [Core Concepts](core_concepts.md) next and grow this Agent into a larger system.

data/docs/guides/integrations.md

@@ -1,149 +1,8 @@
-# Connect MCP, AG-UI, and OpenTelemetry
+# Connect Runs to interfaces and tracing
 
-LittleGhost can load Tools from an MCP server, translate a Run stream for an
-interactive interface, and publish traces. Each integration uses the same
-Agents and Runs you already have.
-
-## Load Tools from an MCP server
-
-An MCP Toolset connects to one server and turns its published operations into
-LittleGhost Tool classes. Add the Toolset through the same Agent `tools`
-declaration used for local Tools:
-
-```ruby
-require "little_ghost/mcp"
-
-class HelpCenterTools < LittleGhost::MCP::Toolset
-  connection url: "https://mcp.example/rpc", timeout: 20
-end
-
-class CustomerSupportAgent < LittleGhost::Agent
-  system_prompt "Use help-center tools for published guidance."
-  tools HelpCenterTools
-end
-
-run = CustomerSupportAgent.ask("How long do refunds take?")
-run.response
-```
-
-`connection` requires `url` and also accepts `headers`, `timeout`, `signer`,
-`allow_insecure_http`, and `max_response_bytes`. Pass a block when credentials
-depend on the current Agent run:
-
-```ruby
-connection do |binding|
-  token = McpAccessTokens.for_actor(binding.run.invocation.actor_id)
-  {
-    url: "https://mcp.example/rpc",
-    headers: {"Authorization" => "Bearer #{token}"},
-    timeout: 20
-  }
-end
-```
-
-The block's `binding` gives it access to the current Run. LittleGhost evaluates
-the block before opening the MCP session, so each Agent run can use credentials
-for its authenticated caller.
-
-By default, the Agent receives every operation published by the server. Their
-normalized server names, such as `search` and `fetch`, become Tool names.
-
-Use `map_tool` when the Agent should receive only part of the server catalog or
-when a generated Tool needs a different name or configuration:
-
-```ruby
-class CuratedHelpCenterTools < LittleGhost::MCP::Toolset
-  connection url: "https://mcp.example/rpc", timeout: 20
-
-  map_tool do |tool_class, definition:, binding:|
-    next unless %w[search fetch].include?(definition.source_name)
-
-    tool_class.tool_name "help_center_#{definition.source_name}"
-    tool_class
-  end
-end
-```
-
-`definition` describes the operation published by the server, and `binding`
-identifies the current Agent run. Return the class after configuring it, or
-return `nil` to omit the operation. Renaming a generated Tool does not change
-the original `Definition#source_name` sent back to the server.
-
-The Agent can call the generated Tools like local Tools. LittleGhost uses one
-local client and transport for the Toolset during the Agent run. The built-in
-HTTP transport does not send an MCP session-termination request. Configure
-server-side expiry, or arrange explicit remote cleanup when the server requires
-it.
-
-Most MCP results need no mapping. LittleGhost returns `structuredContent` as a
-Ruby Hash when present, otherwise it returns the server's text. Server images
-become Artifacts.
-
-Use `map_result` when one operation needs application-specific conversion. This
-example turns the server's download identifier into a deferred Artifact:
-
-```ruby
-map_result do |result, call:, binding:|
-  next result unless call.definition.source_name == "export"
-
-  LittleGhost::Tool::Result.new(
-    value: result.structured_content,
-    artifacts: [
-      LittleGhost::Artifact.deferred(
-        reference: result.metadata.fetch("download_id"),
-        media_type: "application/octet-stream"
-      )
-    ]
-  )
-end
-```
-
-`map_result` receives the complete `MCP::Result`, the `MCP::Call` that produced
-it, and the current binding. Return any Ruby value or `Tool::Result`. Returning
-the supplied result unchanged keeps the default conversion described above.
-MCP images and local Tool artifacts use the same storage and presentation
-rules when `Configuration#artifacts` is enabled. Images and documents are sent
-as model content; their stored references are fallback information rather than
-a second representation. LittleGhost also checks results against
-server-advertised JSON Schema Draft 2020-12 output schemas.
-
-An optional server can fail discovery without preventing Agent construction:
-
-```ruby
-class HelpCenterTools < LittleGhost::MCP::Toolset
-  connection { |binding| McpConnections.help_center(binding) }
-  optional true
-  on_error do |error, binding:|
-    McpAvailability.report(error, run_id: binding.run.invocation.run_id)
-  end
-end
-```
-
-`optional true` converts expected provider and protocol discovery failures
-into an empty Tool set. `on_error` observes only those caught failures.
-Cancellation, deadlines, configuration errors, and application callback
-failures still propagate.
-
-LittleGhost limits the number and total size of discovered operations, the
-complexity of their schemas, and the size and number of returned images.
-`HTTPTransport` also limits each HTTP response and requires HTTPS unless local
-HTTP is explicitly enabled.
-
-> **Safety note:** An MCP server supplies descriptions and results that the model
-> can see. Structural validation does not make that content trustworthy or
-> authorize an operation it suggests. Expose only the operations the Agent
-> needs, use narrowly scoped credentials, and have the server authorize every
-> sensitive call. If a result becomes a deferred Artifact, its resolver must
-> verify that the referenced file belongs to the authenticated caller, fetch
-> only from an intended service, and limit the response size before returning
-> bytes to LittleGhost.
-
-LittleGhost implements its documented client behavior for the [MCP 2025-06-18
-specification](https://modelcontextprotocol.io/specification/2025-06-18).
-
-Use `LittleGhost::MCP::HTTPTransport` and `LittleGhost::MCP::Client` directly
-when you need a custom transport. They produce the same generated Tool classes
-and accept the same mapping callbacks as Toolset.
+Use AG-UI to stream Run events to an interactive client. Use OpenTelemetry to
+publish traces to the backend your application already uses. Neither changes
+the Agent that produced the Run.
 
 ## Send a Run stream through AG-UI
 
@@ -168,13 +27,13 @@ events = LittleGhost::AGUI::Adapter.new.stream(
 events.each { |event| websocket.write(JSON.generate(event)) }
 ```
 
-The adapter translates text, reasoning, Tool activity, usage, retries, trace
-context, subagent activity, and terminal outcomes. It is stateless between
-calls. Your application still owns the connection, backpressure, disconnect
-behavior, and any request state its callbacks need.
+The adapter translates the full Run, including model output, Tool activity,
+retries, subagent activity, and the final outcome. It does not keep state between
+calls. Your application owns the connection, backpressure, disconnect behavior,
+and any request state its callbacks need.
 
-LittleGhost also emits namespaced custom events. Consumers should preserve or
-deliberately ignore event types they don't recognize. See the [AG-UI event
+LittleGhost may emit event types beyond the core AG-UI set. Decide whether the
+client preserves or ignores types it does not recognize. See the [AG-UI event
 documentation](https://docs.ag-ui.com/concepts/events) when implementing the
 client.
 
@@ -183,8 +42,8 @@ client.
 > see the complete Run, then filter fields before sending or storing events.
 
 Calling `each` drives the source stream on the caller's fiber or thread. When a
-client disconnects, stop enumerating and apply the cancellation behavior your
-application needs. Closing the socket can't undo Tool work that already ran.
+client disconnects, stop enumerating and decide whether the application should
+cancel the Run. Closing the socket cannot undo Tool work that already ran.
 
 ## Trace Runs with OpenTelemetry
 
@@ -197,9 +56,9 @@ LittleGhost.configure do |config|
 end
 ```
 
-LittleGhost depends on `opentelemetry-api`, leaving the SDK, processor, and
-exporter up to the application. It emits spans and events for Runs, Agents,
-model calls, Tools, assemblies, sessions, usage, and failures. Active operations
+LittleGhost includes the `opentelemetry-api` integration. Your application
+chooses the SDK, processor, and exporter. The subscriber emits spans and events
+for Runs, model calls, Tools, assemblies, sessions, usage, and failures, and it
 can propagate W3C `traceparent` and `tracestate` fields.
 
 Prompts, messages, responses, Tool arguments, and exception content are omitted
@@ -209,9 +68,9 @@ Avoid putting raw user, order, session, or request IDs in span attributes.
 
 Attribute names follow the evolving [OpenTelemetry GenAI semantic
 conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) where they
-apply. Flush or shut down `LittleGhost::Instrumentation` during application
-shutdown when your backend buffers data.
+apply. If the tracing backend buffers data, flush or shut down
+`LittleGhost::Instrumentation` before the application exits.
 
-See [Running in Production](production.md) for startup, shutdown, and observability,
-[Tools](tools.md) for local and remote Tool behavior, and [Workspaces and
-Sandboxes](sandboxing.md) for child processes and files.
+See [Running in Production](production.md) for startup, shutdown, and
+observability, [MCP](mcp.md) for operations published by remote servers,
+and [Workspaces and Sandboxes](sandboxing.md) for child processes and files.

data/docs/guides/mcp.md

@@ -0,0 +1,288 @@
+# Connect agents to MCP servers
+
+Give an Agent access to operations published by a Model Context Protocol (MCP)
+server without changing how your application calls the Agent.
+`LittleGhost::MCP::Toolset` turns operations discovered by the official MCP Ruby
+client into LittleGhost Tool classes, which join the same `tools` declaration as
+local application Tools.
+
+MCP support is opt-in. Requiring `little_ghost` alone does not install or load
+the SDK or its transports.
+
+## Connect over Streamable HTTP
+
+Add the official SDK and its HTTP dependencies to your bundle:
+
+```ruby
+gem "mcp", "~> 1.3"
+gem "faraday", "~> 2.0"
+gem "event_stream_parser", "~> 1.0"
+```
+
+Require the integration explicitly, then create a Toolset with a `client`
+block. Return a new official client from the block:
+
+```ruby
+require "little_ghost/mcp"
+
+class HelpCenterTools < LittleGhost::MCP::Toolset
+  client do |_binding|
+    transport = MCP::Client::HTTP.new(
+      url: "https://mcp.example/rpc"
+    )
+    MCP::Client.new(transport:)
+  end
+end
+
+class CustomerSupportAgent < LittleGhost::Agent
+  system_prompt "Use help-center tools for published guidance."
+  tools HelpCenterTools
+end
+
+run = CustomerSupportAgent.ask("How long do refunds take?")
+run.response
+```
+
+LittleGhost calls the block once for each Agent run. It connects the client,
+discovers the server's Tools, and closes the transport when the run ends.
+
+The `client` block receives the current `Tool::Binding`. Use it to build headers
+or credentials from authenticated application context without storing them on
+the Toolset:
+
+```ruby
+class AccountTools < LittleGhost::MCP::Toolset
+  client do |binding|
+    token = McpAccessTokens.for_actor(binding.run.invocation.actor_id)
+    transport = MCP::Client::HTTP.new(
+      url: "https://mcp.example/rpc",
+      headers: {"Authorization" => "Bearer #{token}"}
+    )
+    MCP::Client.new(transport:)
+  end
+end
+```
+
+## Connect a local server over standard input and output
+
+A standard input and output (stdio) connection needs only the official SDK:
+
+```ruby
+gem "mcp", "~> 1.3"
+```
+
+Construct the SDK transport in the same `client` block:
+
+```ruby
+class LocalDatabaseTools < LittleGhost::MCP::Toolset
+  client do |_binding|
+    transport = MCP::Client::Stdio.new(
+      command: "bundle",
+      args: ["exec", "database-mcp"],
+      env: {"APP_ENV" => "production"},
+      read_timeout: 30
+    )
+    MCP::Client.new(transport:)
+  end
+end
+```
+
+A stdio server is a child process with the same operating-system permissions as
+your Ruby process. It is not a sandbox. Use an operating-system sandbox when
+you do not fully trust the executable.
+
+The `env` Hash changes only the variables you name. The child inherits every
+other variable from the parent process. Clear sensitive variables explicitly,
+or launch the server through an isolated wrapper when it must not receive
+ambient credentials.
+
+## Configure the official client
+
+Set timeouts, message limits, OAuth, middleware, and other transport behavior
+through the SDK. Keyword arguments on `client` go directly to
+`MCP::Client#connect`; use them for an explicit protocol mode, version, or client
+capability.
+
+### Respond to server requests
+
+A server may need more information while handling a Tool call. MCP calls this
+elicitation. Advertise the capability when connecting, then register a handler
+on the client:
+
+```ruby
+class InteractiveTools < LittleGhost::MCP::Toolset
+  client(capabilities: {elicitation: {}}) do |binding|
+    transport = MCP::Client::HTTP.new(url: "https://mcp.example/rpc")
+    MCP::Client.new(transport:).tap do |official_client|
+      official_client.on_elicitation do |request|
+        Elicitations.answer(request, run: binding.run)
+      end
+    end
+  end
+end
+```
+
+The handler can answer from the current Run or pass the request to an application
+interface. Sampling similarly lets a server request a model call, while roots
+tell a server which directories the application makes available. Configure
+these features on the official client.
+
+Treat every server-initiated handler request as untrusted. Authorize it against
+the current run, restrict roots to intended paths, constrain model sampling and
+its cost, and return only the application data that server is allowed to receive.
+
+Return a new, unconnected client for every run. Building it should not start
+remote work. LittleGhost closes transports that provide `close`, including when
+connection or discovery fails. If a custom transport owns other resources, it
+must release them itself.
+
+Set transport timeouts to match the application's deadline. LittleGhost passes
+Run cancellation and deadlines to Tool discovery and calls, but connection has
+its own timeout behavior.
+
+## Plan concurrency and cancellation
+
+Most applications only need transport timeouts. The details below matter when
+the application uses a Fiber scheduler or runs independent Tools concurrently.
+
+### Connection
+
+LittleGhost connects while it discovers the Agent's Tools. Run cancellation
+does not interrupt connection, so the transport's connection and read timeouts
+control how long it can wait. Choose a scheduler-compatible transport adapter
+when other fibers must continue during that time.
+
+### Tool discovery and calls
+
+Tool discovery and calls honor Run cancellation and deadlines. Cancelling an
+HTTP call returns control to the Run, but the underlying request may continue
+waiting until the server responds or the transport closes.
+
+All Tools for one run share the same client. HTTP calls may overlap when
+LittleGhost runs independent Tools concurrently, so choose a Faraday adapter
+that supports overlapping calls. If the server or transport requires one call
+at a time, mark the generated Tools exclusive:
+
+```ruby
+map_tool do |tool_class, mcp_tool:, binding:|
+  tool_class.exclusive true
+  tool_class
+end
+```
+
+LittleGhost serializes calls through the official stdio transport. If one of
+those calls is cancelled, it closes that run's session rather than risk reading
+a late response as the answer to a later call. A custom or decorated stdio
+transport must provide its own serialization, cancellation behavior, and
+cleanup.
+
+### Server handlers
+
+The server may invoke a handler while other work is active. Write handlers for
+concurrent use and capture the application values they need when building the
+client. Do not rely on fiber-local state inside a handler.
+
+## Select and map Tools
+
+By default, the Agent receives every Tool published by the server. LittleGhost
+normalizes each name for the model and keeps the server's original name for
+calls. Discovery stops after 1,000 Tools or 100 pages, which bounds the work an
+untrusted catalog can create in one run.
+
+Use `map_tool` to omit operations or configure their generated classes:
+
+```ruby
+class CuratedHelpCenterTools < HelpCenterTools
+  map_tool do |tool_class, mcp_tool:, binding:|
+    next unless %w[search fetch].include?(mcp_tool.name)
+
+    tool_class.tool_name "help_center_#{mcp_tool.name}"
+    tool_class
+  end
+end
+```
+
+`mcp_tool` is the Tool published by the official client. Return the generated
+class, a subclass, or `nil` to omit it. Renaming the generated Tool changes the
+name shown to the model, not the name sent back to the server.
+
+LittleGhost sends the server's input schema to the model unchanged. It does not
+validate arguments against that schema; the server must validate them before
+performing an operation. LittleGhost limits schema depth and node count during
+discovery. Configure the transport's message-size limit to bound the bytes
+accepted from a server.
+
+> **Safety note:** Server descriptions and results become visible to the model.
+> Treat them as untrusted content. Expose only the operations the Agent needs,
+> use narrowly scoped credentials, and have the server authorize every sensitive
+> call.
+
+## Convert results
+
+Without a mapping, LittleGhost returns `structuredContent` when the server sends
+it. Otherwise, it returns the text or remaining visible content blocks. MCP
+image blocks become Artifacts.
+
+Suppose the help-center server returns `structuredContent` with an `articles`
+array. Use `map_result` to present each article as a short line:
+
+```ruby
+map_result do |value, mcp_tool:, **|
+  next value unless mcp_tool.name == "search"
+
+  value.fetch("articles").map do |article|
+    "#{article.fetch("title")}: #{article.fetch("url")}"
+  end
+end
+```
+
+`value` is LittleGhost's default conversion, and `mcp_tool` identifies the
+server operation. Return `value` unchanged or replace it with any Ruby value or
+`Tool::Result`. The block can also receive the raw result, sent arguments, and
+current binding; see the [`MCP::Toolset`
+API](rdoc-ref:LittleGhost::MCP::Toolset) for their exact shapes.
+
+Image Artifacts remain attached to the mapped result. A server result marked
+`isError` remains a model-visible Tool error.
+
+For custom images, files, or deferred Artifacts, continue with [Structured
+Results and Content](structured_outputs_and_content.md). A deferred resolver
+must verify ownership, fetch only from the intended service, and limit response
+size.
+
+## Keep an optional server from blocking a run
+
+An optional server can fail discovery without preventing Agent construction:
+
+```ruby
+class OptionalHelpCenterTools < HelpCenterTools
+  optional true
+  on_error do |error, binding:|
+    McpAvailability.report(error, run_id: binding.run.invocation.run_id)
+  end
+end
+```
+
+`optional true` turns an expected connection or protocol error during discovery
+into an empty Tool set. Configuration errors, cancellation, deadlines, and
+failures in application callbacks still stop the run.
+
+## Let the SDK negotiate the protocol version
+
+The [official MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk)
+handles protocol negotiation and transport behavior. Without explicit connect
+options, it negotiates with the server using a protocol version the installed
+SDK supports. Pin `protocol_version` or `mode` only when interoperability
+requires it.
+
+Need sampling, roots, elicitation, or another client capability? Configure it
+on the client you build above. The installed SDK and negotiated protocol version
+determine what is available. Check the [Ruby SDK client
+documentation](https://ruby.sdk.modelcontextprotocol.io/client/) and the
+[versioned MCP specification](https://modelcontextprotocol.io/specification/)
+for the capability you need.
+
+Continue with [Tools](tools.md) for the local Tool boundary,
+[Integrations](integrations.md) to send Runs through AG-UI or OpenTelemetry, or
+the [`MCP::Toolset` API](rdoc-ref:LittleGhost::MCP::Toolset) for exact mapping
+and ownership contracts.