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 specification
  • Generate JSON schemas for tool input validation
Author:
Christian Tzolov

  • Field Details

    • TOOL_CONTEXT_MCP_EXCHANGE_KEY

      public static final String TOOL_CONTEXT_MCP_EXCHANGE_KEY
      The name of tool context key used to store the MCP exchange object.
      See Also:

  • Method Details

    • prefixedToolName

      public static String prefixedToolName(String prefix, String toolName)

    • toSyncToolSpecification

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

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

      Parameters:
      toolCallbacks - the list of tool callbacks to convert
      Returns:
      a list of MCP synchronous tool specification

    • toSyncToolSpecifications

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

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

      Parameters:
      toolCallbacks - the tool callbacks to convert
      Returns:
      a list of MCP synchronous tool specification

    • toSyncToolSpecification

      public static io.modelcontextprotocol.server.McpServerFeatures.SyncToolSpecification toSyncToolSpecification(ToolCallback toolCallback)
      Converts a Spring AI ToolCallback to an MCP SyncToolSpecification. 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 SyncToolSpecification that handles the MCP protocol
      • Provides error handling and result formatting according to MCP specifications
      You can use the ToolCallback builder to create a new instance of ToolCallback using either java.util.function.Function or Method reference.
      Parameters:
      toolCallback - the Spring AI function callback to convert
      Returns:
      an MCP SyncToolSpecification that wraps the function callback
      Throws:
      RuntimeException - if there's an error during the function execution

    • toSyncToolSpecification

      public static io.modelcontextprotocol.server.McpServerFeatures.SyncToolSpecification toSyncToolSpecification(ToolCallback toolCallback, org.springframework.util.MimeType mimeType)
      Converts a Spring AI ToolCallback to an MCP SyncToolSpecification. 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 SyncToolSpecification that handles the MCP protocol
      • Provides error handling and result formatting according to MCP specifications
      Parameters:
      toolCallback - the Spring AI function callback to convert
      mimeType - the MIME type of the output content
      Returns:
      an MCP SyncToolSpecification that wraps the function callback
      Throws:
      RuntimeException - if there's an error during the function execution

    • getMcpExchange

      public static Optional<io.modelcontextprotocol.server.McpSyncServerExchange> getMcpExchange(ToolContext toolContext)
      Retrieves the MCP exchange object from the provided tool context if it exists.
      Parameters:
      toolContext - the tool context from which to retrieve the MCP exchange
      Returns:
      the MCP exchange object, or null if not present in the context

    • toAsyncToolSpecifications

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

      This method processes multiple tool callbacks in bulk, converting each one to its corresponding MCP tool specification while adding asynchronous execution capabilities. The resulting specifications 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 specifications

    • toAsyncToolSpecifications

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

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

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

    • toAsyncToolSpecification

      public static io.modelcontextprotocol.server.McpServerFeatures.AsyncToolSpecification toAsyncToolSpecification(ToolCallback toolCallback)
      Converts a Spring AI tool callback to an MCP asynchronous tool specification.

      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 specification
      • Wraps the synchronous execution in a reactive Mono
      • Configures execution on a bounded elastic scheduler for non-blocking operation

      The resulting async specification 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 specification that wraps the tool callback
      See Also:
      • McpServerFeatures.AsyncToolSpecification
      • Mono
      • Schedulers.boundedElastic()

    • toAsyncToolSpecification

      public static io.modelcontextprotocol.server.McpServerFeatures.AsyncToolSpecification toAsyncToolSpecification(ToolCallback toolCallback, org.springframework.util.MimeType mimeType)
      Converts a Spring AI tool callback to an MCP asynchronous tool specification.

      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 specification
      • Wraps the synchronous execution in a reactive Mono
      • Configures execution on a bounded elastic scheduler for non-blocking operation

      The resulting async specification 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
      mimeType - the MIME type of the output content
      Returns:
      an MCP asynchronous tool specificaiotn that wraps the tool callback
      See Also:
      • McpServerFeatures.AsyncToolSpecification
      • Schedulers.boundedElastic()

    • getToolCallbacksFromSyncClients

      public static List<ToolCallback> getToolCallbacksFromSyncClients(io.modelcontextprotocol.client.McpSyncClient... mcpClients)
      Convenience method to get tool callbacks from multiple synchronous MCP clients.

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

      Parameters:
      mcpClients - the synchronous MCP clients to get callbacks from
      Returns:
      a list of tool callbacks from all provided clients
      See Also:

    • getToolCallbacksFromSyncClients

      public static List<ToolCallback> getToolCallbacksFromSyncClients(List<io.modelcontextprotocol.client.McpSyncClient> mcpClients)
      Gets tool callbacks from a list of synchronous MCP clients.

      This method:

      1. Takes a list of synchronous MCP clients
      2. Creates a provider for each client
      3. Retrieves and combines all tool callbacks into a single list
      Parameters:
      mcpClients - the list of synchronous MCP clients to get callbacks from
      Returns:
      a list of tool callbacks from all provided clients

    • getToolCallbacksFromAsyncClients

      public static List<ToolCallback> getToolCallbacksFromAsyncClients(io.modelcontextprotocol.client.McpAsyncClient... asyncMcpClients)
      Convenience method to get tool callbacks from multiple asynchronous MCP clients.

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

      Parameters:
      asyncMcpClients - the asynchronous MCP clients to get callbacks from
      Returns:
      a list of tool callbacks from all provided clients
      See Also:

    • getToolCallbacksFromAsyncClients

      public static List<ToolCallback> getToolCallbacksFromAsyncClients(List<io.modelcontextprotocol.client.McpAsyncClient> asyncMcpClients)
      Gets tool callbacks from a list of asynchronous MCP clients.

      This method:

      1. Takes a list of asynchronous MCP clients
      2. Creates a provider for each client
      3. Retrieves and combines all tool callbacks into a single list
      Parameters:
      asyncMcpClients - the list of asynchronous MCP clients to get callbacks from
      Returns:
      a list of tool callbacks from all provided clients