Class AsyncModernMcpToolCallbackProvider

java.lang.Object
org.springframework.ai.mcp.modern.client.AsyncModernMcpToolCallbackProvider
All Implemented Interfaces:
AsyncModernMcpChangeListener, ToolCallbackProvider, org.springframework.core.Ordered

public final class AsyncModernMcpToolCallbackProvider extends Object implements ToolCallbackProvider, AsyncModernMcpChangeListener, org.springframework.core.Ordered
Exposes the tools of modern MCP servers as Spring AI ToolCallbacks.

Each call to getToolCallbacks() asks every AsyncModernMcpConnection for the client that serves the current request, lists that client's tools, and returns callbacks bound to that client. A ChatClient calls this method once for each request, so register the provider with defaultToolCallbacks(provider) rather than the callbacks it returns.

The server decides how long a tool listing may be kept and who may share it, with the ttlMs and cacheScope of the listing:

  • A listing with a ttlMs of zero is never kept, and every call to getToolCallbacks() lists the tools again. Servers send zero unless configured otherwise.
  • A public listing is the same for every caller. The provider keeps it for its ttlMs and uses it for all requests, whichever client serves them.
  • A private listing may differ from caller to caller, so the provider does not keep it. It is only kept by a client that outlives a request, as the client of a shared connection does, or the client that a scoped connection keeps for a user. Use a shared connection when the application calls the server under a single identity.
A tool call is never served from a kept listing: it always goes to the server, through the client of the request that resolved the callback.

A kept listing is used until its ttlMs has passed. To drop it as soon as the server reports that its tools changed, register the provider as a listener of an AsyncModernMcpChangeSubscriber, which keeps a listen stream open to the server.

The tools are listed through the asynchronous client, and the call blocks until the listings are there, as the ToolCallbackProvider contract requires. So it must not be made on a thread that may not block, such as an event loop. The caller of a listing is the transport context of its connection, which is read on the calling thread.

A server that cannot be reached does not fail the call: its tools are left out and a warning is logged, so the tools of the other connections stay usable. A server counts as unreachable when the connection cannot be established, the exchange times out or breaks, or the server answers with a 5xx, 408 or 429 status. Every other failure is thrown, in particular an authorization failure, so that the application can ask the user to log in again.

A server that could not be reached is not asked again until a cool-down time has passed (30 seconds unless set otherwise). Otherwise a server that accepts connections but does not answer would hold up every request for the whole timeout of the listing.

Since:
2.1.0
Author:
Christian Tzolov
See Also:
  • Method Details

    • builder

      Creates a builder for a AsyncModernMcpToolCallbackProvider.
      Returns:
      the builder
    • getToolCallbacks

      public ToolCallback[] getToolCallbacks()
      Returns a callback for each tool of every connection that the filter accepts. The tools of a connection are listed unless a public listing of them is still kept. The callbacks of a connection are bound to the client that connection returned for this call. The tools of a connection whose server cannot be reached are left out, and that server is not asked again until the cool-down time has passed.
      Specified by:
      getToolCallbacks in interface ToolCallbackProvider
      Returns:
      the tool callbacks
      Throws:
      IllegalStateException - if two tools end up with the same name
    • invalidateToolListing

      public void invalidateToolListing(String connectionName)
      Drops the kept tool listing of a connection, so that the next call to getToolCallbacks() lists its tools again. Use it when the tools of the server are known to have changed before the ttlMs of the listing has passed. A client that keeps a listing itself, as a shared client or a client that a AsyncModernMcpClientScope keeps for a user does, asks the server the next time it lists the tools.
      Parameters:
      connectionName - the name of the connection
    • getOrder

      public int getOrder()
      The provider hears about a change before the other listeners of an AsyncModernMcpChangeSubscriber, so that a listener that asks it for the tools finds the kept listing dropped.
      Specified by:
      getOrder in interface org.springframework.core.Ordered
      Returns:
      the highest precedence
    • streamEstablished

      public reactor.core.publisher.Mono<Void> streamEstablished(McpModernConnectionInfo connectionInfo)
      Ends the cool-down of the connection, if its server could not be reached before: a listen stream that was established shows that it can be reached again.
      Specified by:
      streamEstablished in interface AsyncModernMcpChangeListener
      Parameters:
      connectionInfo - the connection whose server accepted the stream
      Returns:
      completes when the listener has dealt with it
    • changed

      public reactor.core.publisher.Mono<Void> changed(McpModernConnectionInfo connectionInfo, io.modelcontextprotocol.modern.client.SubscriptionEvent event)
      Drops the kept tool listing of the connection when its server reports that its tools changed.
      Specified by:
      changed in interface AsyncModernMcpChangeListener
      Parameters:
      connectionInfo - the connection whose server changed
      event - what changed: a SubscriptionEvent.ToolsListChanged, a SubscriptionEvent.PromptsListChanged, a SubscriptionEvent.ResourcesListChanged or a SubscriptionEvent.ResourceUpdated
      Returns:
      completes when the listener has dealt with the change
    • changesMayBeMissed

      public reactor.core.publisher.Mono<Void> changesMayBeMissed(McpModernConnectionInfo connectionInfo)
      Drops the kept tool listing of the connection, because a change of its tools may have gone unreported.
      Specified by:
      changesMayBeMissed in interface AsyncModernMcpChangeListener
      Parameters:
      connectionInfo - the connection whose server may have changed
      Returns:
      completes when the listener has dealt with it