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.

Native Image Support

The McpHints class provides GraalVM native image hints for MCP schema classes. This class automatically registers all necessary reflection hints for MCP schema classes when building native images.