llm4s-docs
API
Generated with
llm4s-docs/org.llm4s/org.llm4s.mcp/MCPToolRegistry

MCPToolRegistry

org.llm4s.mcp.MCPToolRegistry
See theMCPToolRegistry companion object
class MCPToolRegistry(mcpServers: Seq[MCPServerConfig], localTools: Seq[ToolFunction[_, _]], cacheTTL: FiniteDuration, initializeOnStartup: Boolean) extends ToolRegistry, AutoCloseable

ToolRegistry that transparently integrates local tools with tools discovered from one or more MCP servers.

== Tool lookup order == execute tries local tools first. Only when a local tool with the requested name is not found does it query MCP servers. A tool defined locally shadows any MCP tool with the same name.

== Caching == Tool lists fetched from each MCP server are cached for cacheTTL (default 10 minutes). A stale cache entry is refreshed lazily on the next call that requires that server's tools. Call clearCache() or refreshCache() to invalidate proactively.

== Startup initialisation == When initializeOnStartup is true (the default), the registry fetches and caches tools from all configured MCP servers during construction. Set it to false in tests to defer or skip network calls.

== Error handling == If an MCP server cannot be reached or returns an error, the failure is logged and that server contributes no tools — the registry never throws during tool lookup. Its client is closed and evicted, and its cached tools and hints are dropped with it, because those tools call through that client: the model is never offered a tool that cannot be called. The next lookup attempts a fresh connection. A refresh that is only cancelled (the thread was interrupted) keeps the client and the tools already fetched.

== Lifecycle == Implements AutoCloseable; call close() (or use Using.resource) to shut down all active MCP transport connections.

Value parameters

cacheTTL

How long a server's tool list is considered fresh; defaults to 10 minutes

initializeOnStartup

When false, MCP connections are deferred until first use

localTools

Tools provided directly without a remote server call

mcpServers

MCP server configurations to query for remote tools

Attributes

Companion
object
Graph
Supertypes
trait AutoCloseable
class ToolRegistry
class Object
trait Matchable
class Any

Members list

Value members

Concrete methods

def clearCache(): Unit

Discards all cached tool lists, forcing a fresh fetch from each MCP server on the next tool lookup.

Discards all cached tool lists, forcing a fresh fetch from each MCP server on the next tool lookup.

Attributes

override def close(): Unit

Attributes

Definition Classes
AutoCloseable
def closeMCPClients(): Unit

Closes all active MCP transport connections and removes them from the internal client map. After this call the registry still holds its local tools; MCP tools will be re-fetched (creating new connections) on the next lookup.

Closes all active MCP transport connections and removes them from the internal client map. After this call the registry still holds its local tools; MCP tools will be re-fetched (creating new connections) on the next lookup.

Attributes

override def execute(request: ToolCallRequest): Either[ToolCallError, Value]

Executes a tool call synchronously, wrapping any thrown exception.

Executes a tool call synchronously, wrapping any thrown exception.

We use Try here (rather than org.llm4s.core.safety.Safety.safely) so that tool execution remains independent of the Safety API and returns Either for direct use by retry/timeout logic. Safety is still used elsewhere in the codebase (e.g. tracing, agent entry points).

Exceptions thrown inside the tool implementation are caught and converted to ToolCallError.ExecutionError with the original throwable preserved (so retry logic can treat e.g. IOException as retryable). Callers always receive a typed Either and never need to guard against unexpected exceptions from tool code.

Tool-returned Left values are propagated unchanged, so callers may receive any ToolCallError subtype that the tool itself produces (not only ExecutionError).

Value parameters

request

The tool name and pre-parsed JSON arguments.

Attributes

Returns

Right(result) on success; Left(ToolCallError.UnknownFunction) when no tool with the given name is registered; Left(ToolCallError.ExecutionError) when the tool throws an exception; or Left(error) with the tool's own ToolCallError when the tool returns a Left directly.

Definition Classes
def getAllTools: Seq[ToolFunction[_, _]]
override def getOpenAITools(strict: Boolean): Arr

Generate OpenAI tool definitions for all tools.

Generate OpenAI tool definitions for all tools.

Value parameters

strict

When true (default), all object properties are treated as required.

Attributes

Returns

A ujson.Arr containing one tool-definition object per registered tool

Definition Classes
def healthCheck(): Map[String, Boolean]

Attempts to initialise a connection to each configured MCP server and reports whether the handshake succeeded.

Attempts to initialise a connection to each configured MCP server and reports whether the handshake succeeded.

Each server is tested by creating (or reusing) its client and calling initialize(). The returned map contains one entry per server, keyed by MCPServerConfig.name, with true meaning the server responded successfully and false meaning initialisation failed (connection refused, timeout, protocol mismatch, etc.).

Attributes

Returns

map from server name to health status; keys match mcpServers.map(_.name)

def refreshCache(): Unit

Eagerly re-fetches tool lists from all configured MCP servers and updates the cache. Useful after deploying changes to MCP server tool definitions. Errors for individual servers are logged but do not prevent other servers from being refreshed.

Eagerly re-fetches tool lists from all configured MCP servers and updates the cache. Useful after deploying changes to MCP server tool definitions. Errors for individual servers are logged but do not prevent other servers from being refreshed.

Attributes

def toolHints(name: String): Option[ToolHints]

The hints the MCP server declares for the tool name through its tool annotations, as of the last discovery of that server's tools (tools, getAllTools or execute trigger it); None for a tool no MCP server advertises, for one a local tool shadows, and for any tool of a server whose last discovery failed.

The hints the MCP server declares for the tool name through its tool annotations, as of the last discovery of that server's tools (tools, getAllTools or execute trigger it); None for a tool no MCP server advertises, for one a local tool shadows, and for any tool of a server whose last discovery failed.

'''Only a trusted server has hints.''' The MCP specification requires annotations from an untrusted server to be treated as untrusted, and ApprovalMiddleware.unlessReadOnly skips approval for a tool whose hints say read-only, so a server's own claim must not relax approval by default. A server configured with trustAnnotations = false (the default, see MCPServerConfig) yields None for every one of its tools; pass registry.toolHints(name).getOrElse(ToolHints.default) to AgentTool.fromToolFunction and an untrusted tool keeps the conservative defaults, which require approval. See MCPClient.getToolHints.

Attributes

override def tools: Seq[ToolFunction[_, _]]

All tools registered in this registry.

All tools registered in this registry.

Attributes

Definition Classes

Inherited methods

def execute(request: ToolCallRequest, config: ToolExecutionConfig)(implicit ec: ExecutionContext): Either[ToolCallError, Value]

Executes a tool call with optional per-tool timeout and retry.

Executes a tool call with optional per-tool timeout and retry.

When config is default (no timeout, no retry), behavior is identical to execute.

Value parameters

config

Optional timeout and retry policy

ec

ExecutionContext required when timeout or retry is used

request

The tool call request

Attributes

Inherited from:
ToolRegistry
def executeAll(requests: Seq[ToolCallRequest], strategy: ToolExecutionStrategy, config: ToolExecutionConfig)(implicit ec: ExecutionContext): Future[Seq[Either[ToolCallError, Value]]]

Execute multiple tool calls with a configurable strategy.

Execute multiple tool calls with a configurable strategy.

Value parameters

ec

ExecutionContext for async execution

requests

The tool call requests to execute

strategy

Execution strategy (Sequential, Parallel, or ParallelWithLimit)

Attributes

Returns

Future containing results in the same order as requests

Inherited from:
ToolRegistry
def executeAsync(request: ToolCallRequest, config: ToolExecutionConfig)(implicit ec: ExecutionContext): Future[Either[ToolCallError, Value]]

Execute a tool call asynchronously with optional timeout and retry.

Execute a tool call asynchronously with optional timeout and retry.

Each attempt runs on a thread of ec and holds it for the attempt only. The backoff between two attempts holds no thread: it is a scheduled delay, after which the next attempt is dispatched to ec, so a small pool keeps serving other work while many calls wait to retry. (The synchronous execute still waits on its caller's thread, interruptibly, because a synchronous caller has nothing to resume.)

Value parameters

config

Optional timeout and retry policy

ec

ExecutionContext for async execution

request

The tool call request

Attributes

Inherited from:
ToolRegistry
def executeAsync(request: ToolCallRequest)(implicit ec: ExecutionContext): Future[Either[ToolCallError, Value]]

Execute a tool call asynchronously.

Execute a tool call asynchronously.

Wraps synchronous execution in a Future for non-blocking operation. NOTE: Tool execution typically involves blocking I/O. We use blocking to hint the ExecutionContext to expand its pool if necessary.

Value parameters

ec

ExecutionContext for async execution

request

The tool call request

Attributes

Returns

Future containing the result

Inherited from:
ToolRegistry
def getTool(name: String): Option[ToolFunction[_, _]]

Get a specific tool by name

Get a specific tool by name

Attributes

Inherited from:
ToolRegistry
Generated with