|
This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0! |
MCP Utilities
The MCP utilities provide foundational support for integrating Model Context Protocol with Spring AI applications. These utilities enable seamless communication between Spring AI’s tool system and MCP servers, supporting both synchronous and asynchronous operations. They are typically used for programmatic MCP Client and Server configuration and interaction. For a more streamlined configuration, consider using the boot starters.
ToolCallback Utility
Tool Callback Adapter
Adapts MCP tools to Spring AI’s tool interface with both synchronous and asynchronous execution support.
-
Sync
-
Async
McpSyncClient mcpClient = // obtain MCP client
Tool mcpTool = // obtain MCP tool definition
ToolCallback callback = SyncMcpToolCallback.builder()
.mcpClient(mcpClient)
.tool(mcpTool)
.build();
// Use the tool through Spring AI's interfaces
ToolDefinition definition = callback.getToolDefinition();
String result = callback.call("{\"param\": \"value\"}");
McpAsyncClient mcpClient = // obtain MCP client
Tool mcpTool = // obtain MCP tool definition
ToolCallback callback = AsyncMcpToolCallback.builder()
.mcpClient(mcpClient)
.tool(mcpTool)
.build();
// Use the tool through Spring AI's interfaces
ToolDefinition definition = callback.getToolDefinition();
String result = callback.call("{\"param\": \"value\"}");
Tool Callback Providers
Discovers and provides MCP tools from MCP clients.
-
Sync
-
Async
McpSyncClient mcpClient = // obtain MCP client
ToolCallbackProvider provider = SyncMcpToolCallbackProvider.builder()
.mcpClients(mcpClient)
.build();
// Get all available tools
ToolCallback[] tools = provider.getToolCallbacks();
For multiple clients:
List<McpSyncClient> clients = // obtain list of clients
List<ToolCallback> callbacks = SyncMcpToolCallbackProvider.syncToolCallbacks(clients);
For dynamic selection of a subset of clients
@Autowired
private List<McpSyncClient> mcpSyncClients;
public ToolCallbackProvider buildProvider(Set<String> allowedServerNames) {
// Filter by server.name().
List<McpSyncClient> selected = mcpSyncClients.stream()
.filter(c -> allowedServerNames.contains(c.getServerInfo().name()))
.toList();
return SyncMcpToolCallbackProvider.builder()
.mcpClients(selected)
.build();
}
McpAsyncClient mcpClient = // obtain MCP client
ToolCallbackProvider provider = AsyncMcpToolCallbackProvider.builder()
.mcpClients(mcpClient)
.build();
// Get all available tools
ToolCallback[] tools = provider.getToolCallbacks();
For multiple clients:
List<McpAsyncClient> clients = // obtain list of clients
Flux<ToolCallback> callbacks = AsyncMcpToolCallbackProvider.asyncToolCallbacks(clients);
McpToolUtils
ToolCallbacks to ToolSpecifications
Converting Spring AI tool callbacks to MCP tool specifications:
-
Sync
-
Async
List<ToolCallback> toolCallbacks = // obtain tool callbacks
List<McpServerFeatures.SyncToolSpecification> syncToolSpecs = McpToolUtils.toSyncToolSpecification(toolCallbacks);
then you can use the McpServer.SyncSpecification to register the tool specifications:
McpServer.SyncSpecification<?> syncSpec = ...
syncSpec.tools(syncToolSpecs);
List<ToolCallback> toolCallbacks = // obtain tool callbacks
List<McpServerFeatures.AsyncToolSpecification> asyncToolSpecifications = McpToolUtils.toAsyncToolSpecifications(toolCallbacks);
then you can use the McpServer.AsyncSpecification to register the tool specifications:
McpServer.AsyncSpecification<?> asyncSpec = ...
asyncSpec.tools(asyncToolSpecifications);
MCP Clients to ToolCallbacks
Getting tool callbacks from MCP clients
-
Sync
-
Async
List<McpSyncClient> syncClients = // obtain sync clients
List<ToolCallback> syncCallbacks = McpToolUtils.getToolCallbacksFromSyncClients(syncClients);
List<McpAsyncClient> asyncClients = // obtain async clients
List<ToolCallback> asyncCallbacks = McpToolUtils.getToolCallbacksFromAsyncClients(asyncClients);
McpModernToolUtils
McpModernToolUtils converts Spring AI tool callbacks to the tools of an MCP 2026-07-28 server.
The auto-configuration already converts the ToolCallback and ToolCallbackProvider beans, so you need it only when you build tools yourself, for example to add them to the in-memory tool repository at runtime.
-
Sync
-
Async
List<ToolCallback> toolCallbacks = // obtain tool callbacks
List<McpSyncTool> tools = McpModernToolUtils.toSyncTools(toolCallbacks);
// Add one tool to a running server
ToolCallback toolCallback = // obtain a tool callback
InMemorySyncToolRepository toolRepository = // inject the repository bean
toolRepository.add(McpModernToolUtils.toSyncTool(toolCallback));
List<ToolCallback> toolCallbacks = // obtain tool callbacks
List<McpAsyncTool> tools = McpModernToolUtils.toAsyncTools(toolCallbacks);
The tool returns the callback result as text content.
toSyncTool(toolCallback, mimeType) and toAsyncTool(toolCallback, mimeType) return it as image content when the MIME type is an image type.
The asynchronous tools run the blocking callback through McpModernAsyncUtils.fromBlocking.
The callback receives the McpRequestContext of the current call in its ToolContext:
McpRequestContext requestContext = McpModernToolUtils.getMcpRequestContext(toolContext);
It returns null when the callback is not called by a 2026-07-28 server.