Package org.springframework.ai.mcp

Class McpToolUtils

java.lang.Object
org.springframework.ai.mcp.McpToolUtils
public final class McpToolUtils extends Object
Utility class that provides helper methods for working with Model Context Protocol (MCP) tools in a Spring AI environment. This class facilitates the integration between Spring AI's tool callbacks and MCP's tool system.

The MCP tool system enables servers to expose executable functionality to language models, allowing them to interact with external systems, perform computations, and take actions in the real world. Each tool is uniquely identified by a name and includes metadata describing its schema.

This helper class provides methods to:

  • Convert Spring AI's ToolCallback instances to MCP tool registrations
  • Generate JSON schemas for tool input validation
Author:
Christian Tzolov

  • Method Details

    • toSyncToolRegistration

      public static List<io.modelcontextprotocol.server.McpServerFeatures.SyncToolRegistration> toSyncToolRegistration(List<ToolCallback> toolCallbacks)
      Converts a list of Spring AI tool callbacks to MCP synchronous tool registrations.

      This method processes multiple tool callbacks in bulk, converting each one to its corresponding MCP tool registration while maintaining synchronous execution semantics.

      Parameters:
      toolCallbacks - the list of tool callbacks to convert
      Returns:
      a list of MCP synchronous tool registrations
      See Also:

    • toSyncToolRegistration

      public static List<io.modelcontextprotocol.server.McpServerFeatures.SyncToolRegistration> toSyncToolRegistration(ToolCallback... toolCallbacks)
      Convenience method to convert a variable number of tool callbacks to MCP synchronous tool registrations.

      This is a varargs wrapper around toSyncToolRegistration(List) for easier usage when working with individual callbacks.

      Parameters:
      toolCallbacks - the tool callbacks to convert
      Returns:
      a list of MCP synchronous tool registrations
      See Also:

    • toSyncToolRegistration

      public static io.modelcontextprotocol.server.McpServerFeatures.SyncToolRegistration toSyncToolRegistration(ToolCallback toolCallback)
      Converts a Spring AI FunctionCallback to an MCP SyncToolRegistration. This enables Spring AI functions to be exposed as MCP tools that can be discovered and invoked by language models.

      The conversion process:

      • Creates an MCP Tool with the function's name and input schema
      • Wraps the function's execution in a SyncToolRegistration that handles the MCP protocol
      • Provides error handling and result formatting according to MCP specifications
      You can use the FunctionCallback builder to create a new instance of FunctionCallback using either java.util.function.Function or Method reference.
      Parameters:
      toolCallback - the Spring AI function callback to convert
      Returns:
      an MCP SyncToolRegistration that wraps the function callback
      Throws:
      RuntimeException - if there's an error during the function execution

    • toAsyncToolRegistration

      public static List<io.modelcontextprotocol.server.McpServerFeatures.AsyncToolRegistration> toAsyncToolRegistration(List<ToolCallback> toolCallbacks)
      Converts a list of Spring AI tool callbacks to MCP asynchronous tool registrations.

      This method processes multiple tool callbacks in bulk, converting each one to its corresponding MCP tool registration while adding asynchronous execution capabilities. The resulting registrations will execute their tools on a bounded elastic scheduler.

      Parameters:
      toolCallbacks - the list of tool callbacks to convert
      Returns:
      a list of MCP asynchronous tool registrations
      See Also:

    • toAsyncToolRegistration

      public static List<io.modelcontextprotocol.server.McpServerFeatures.AsyncToolRegistration> toAsyncToolRegistration(ToolCallback... toolCallbacks)
      Convenience method to convert a variable number of tool callbacks to MCP asynchronous tool registrations.

      This is a varargs wrapper around toAsyncToolRegistration(List) for easier usage when working with individual callbacks.

      Parameters:
      toolCallbacks - the tool callbacks to convert
      Returns:
      a list of MCP asynchronous tool registrations
      See Also:

    • toAsyncToolRegistration

      public static io.modelcontextprotocol.server.McpServerFeatures.AsyncToolRegistration toAsyncToolRegistration(ToolCallback toolCallback)
      Converts a Spring AI tool callback to an MCP asynchronous tool registration.

      This method enables Spring AI tools to be exposed as asynchronous MCP tools that can be discovered and invoked by language models. The conversion process:

      • First converts the callback to a synchronous registration
      • Wraps the synchronous execution in a reactive Mono
      • Configures execution on a bounded elastic scheduler for non-blocking operation

      The resulting async registration will:

      • Execute the tool without blocking the calling thread
      • Handle errors and results asynchronously
      • Provide backpressure through Project Reactor
      Parameters:
      toolCallback - the Spring AI tool callback to convert
      Returns:
      an MCP asynchronous tool registration that wraps the tool callback
      See Also:
      • McpServerFeatures.AsyncToolRegistration
      • Mono
      • Schedulers.boundedElastic()

    • getToolCallbacks

      public static List<ToolCallback> getToolCallbacks(io.modelcontextprotocol.client.McpSyncClient... mcpClients)

    • getToolCallbacks

      public static List<ToolCallback> getToolCallbacks(List<io.modelcontextprotocol.client.McpSyncClient> mcpClients)