= MCP Utilities
:page-title: Spring AI 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.

[tabs]
======
Sync::
+
[source,java]
----
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\"}");
----

Async::
+
[source,java]
----
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.

[tabs]
======
Sync::
+
[source,java]
----
McpSyncClient mcpClient = // obtain MCP client
ToolCallbackProvider provider = new SyncMcpToolCallbackProvider(mcpClient);

// Get all available tools
ToolCallback[] tools = provider.getToolCallbacks();
----
+
For multiple clients:
+
[source,java]
----
List<McpSyncClient> clients = // obtain list of clients
List<ToolCallback> callbacks = SyncMcpToolCallbackProvider.syncToolCallbacks(clients);
----

Async::
+
[source,java]
----
McpAsyncClient mcpClient = // obtain MCP client
ToolCallbackProvider provider = new AsyncMcpToolCallbackProvider(mcpClient);

// Get all available tools
ToolCallback[] tools = provider.getToolCallbacks();
----
+
For multiple clients:
+
[source,java]
----
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:

[tabs]
======
Sync::
+
[source,java]
----
List<ToolCallback> toolCallbacks = // obtain tool callbacks
List<SyncToolSpecifications> syncToolSpecs = McpToolUtils.toSyncToolSpecifications(toolCallbacks);
----
+
then you can use the `McpServer.SyncSpecification` to register the tool specifications:
+
[source,java]
----
McpServer.SyncSpecification syncSpec = ...
syncSpec.tools(syncToolSpecs);
----

Async::
+
[source,java]
----
List<ToolCallback> toolCallbacks = // obtain tool callbacks
List<AsyncToolSpecification> asyncToolSpecifications = McpToolUtils.toAsyncToolSpecifications(toolCallbacks);
----
+
then you can use the `McpServer.AsyncSpecification` to register the tool specifications:
+
[source,java]
----
McpServer.AsyncSpecification asyncSpec = ...
asyncSpec.tools(asyncToolSpecifications);
----
======

=== MCP Clients to ToolCallbacks

Getting tool callbacks from MCP clients

[tabs]
======
Sync::
+
[source,java]
----
List<McpSyncClient> syncClients = // obtain sync clients
List<ToolCallback> syncCallbacks = McpToolUtils.getToolCallbacksFromSyncClients(syncClients);
----

Async::
+
[source,java]
----
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.
