This version is still in development and is not considered stable yet. For the latest snapshot version, please use Spring AI 1.0.0-SNAPSHOT!

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 = new SyncMcpToolCallback(mcpClient, mcpTool);

// 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 = new AsyncMcpToolCallback(mcpClient, mcpTool);

// 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 = new SyncMcpToolCallbackProvider(mcpClient);

// Get all available tools
ToolCallback[] tools = provider.getToolCallbacks();

For multiple clients:

List<McpSyncClient> clients = // obtain list of clients
List<ToolCallback> callbacks = SyncMcpToolCallbackProvider.syncToolCallbacks(clients);
McpAsyncClient mcpClient = // obtain MCP client
ToolCallbackProvider provider = new AsyncMcpToolCallbackProvider(mcpClient);

// 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<SyncToolSpecifications> syncToolSpecs = McpToolUtils.toSyncToolSpecifications(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<AsyncToolSpecification> asyncToolSpecificaitons = McpToolUtils.toAsyncToolSpecifications(toolCallbacks);

then you can use the McpServer.AsyncSpecification to register the tool specifications:

McpServer.AsyncSpecification asyncSpec = ...
asyncSpec.tools(asyncToolSpecificaitons);

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);

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.