Spring AI MCP Spring

Spring Integration module for Model Control Protocol (MCP) that provides Spring-specific functionality for working with MCP clients.

Overview

The spring-ai-mcp module is part of the Spring AI MCP project. It provides Spring Framework integration for the Model Control Protocol (MCP), enabling seamless integration of MCP functionality within Spring applications.

Features

  • Spring integration for MCP clients

  • Bidirectional conversion between Spring AI function callbacks and MCP tools

  • JSON schema generation for tool input validation

  • Automatic type conversion and error handling

  • Integration with Spring AI’s function calling capabilities

Main Components

McpFunctionCallback

The McpFunctionCallback class implements Spring AI’s FunctionCallback interface and provides integration between Spring AI’s function calling system and MCP tools. Key features include:

  • Automatic conversion between JSON and Java objects for tool arguments

  • Synchronous tool execution support

  • Error handling and result formatting

  • Integration with Spring AI’s function calling system

Example usage:

// Create an MCP client
McpSyncClient mcpClient = McpClient.using(transport)
    .sync();

// Create a function callback for an MCP tool
Tool calculatorTool = new Tool("calculator", "Basic calculator",
    Map.of("operation", "string", "a", "number", "b", "number"));
FunctionCallback callback = new McpFunctionCallback(mcpClient, calculatorTool);

// Use the callback with Spring AI
String result = callback.call("{\"operation\": \"add\", \"a\": 2, \"b\": 3}");

ToolHelper

The ToolHelper utility class facilitates the integration between Spring AI’s function callbacks and MCP’s tool system. It provides methods for:

  • Converting Spring AI’s FunctionCallback instances to MCP tool registrations

  • Generating JSON schemas for tool input validation

  • Handling error cases and result formatting

Example usage:

// Convert Spring AI function callbacks to MCP tool registrations
List<FunctionCallback> callbacks = List.of(
    new CalculatorFunction(),
    new WeatherFunction()
);
List<ToolRegistration> tools = ToolHelper.toToolRegistration(callbacks);

// Generate JSON schema for tool inputs
Map<String, Class<?>> inputTypes = Map.of(
    "calculator", CalculatorInput.class,
    "weather", WeatherInput.class
);
String schema = ToolHelper.generateJsonSchema(inputTypes);

Converting Function Callbacks to Tools

The ToolHelper provides several methods to convert Spring AI function callbacks to MCP tools:

// Convert a single function callback
ToolRegistration tool = ToolHelper.toToolRegistration(myCallback);

// Convert multiple callbacks
List<ToolRegistration> tools = ToolHelper.toToolRegistration(callback1, callback2);

// Convert a list of callbacks
List<ToolRegistration> tools = ToolHelper.toToolRegistration(callbackList);

JSON Schema Generation

The ToolHelper can generate JSON schemas for tool input validation:

// Using default ObjectMapper
String schema = ToolHelper.generateJsonSchema(inputTypes);

// Using custom ObjectMapper
ObjectMapper mapper = new ObjectMapper();
String schema = ToolHelper.generateJsonSchema(inputTypes, mapper);

The generated schema follows the JSON Schema Draft 2020-12 specification and: * Validates the structure of tool inputs * Excludes ToolContext class from schema generation * Uses Jackson’s JsonSchemaGenerator for accurate type representation

Usage

To use this module, add the following dependency to your Maven project:

<dependency>
    <groupId>org.springframework.experimental</groupId>
    <artifactId>spring-ai-mcp</artifactId>
</dependency>

Reffer to the Dependency Management page for more information.

Example: Creating an MCP Tool Server with Spring AI Functions

@Configuration
class McpConfig {

    @Bean
    McpServer mcpServer(List<FunctionCallback> callbacks) {
        // Convert Spring AI callbacks to MCP tools
        List<ToolRegistration> tools = ToolHelper.toToolRegistration(callbacks);

        return McpServer.using(transport)
            .info("spring-ai-server", "1.0.0")
            .tools(tools)
            .sync();
    }

    @Bean
    FunctionCallback calculatorFunction() {
        return FunctionCallback.builder()
            .name("calculator")
            .description("Basic calculator")
            .function(input -> {
                // Function implementation
                return result;
            })
            .build();
    }
}

This configuration: 1. Creates Spring AI function callbacks 2. Converts them to MCP tools using ToolHelper 3. Registers the tools with an MCP server 4. Makes the tools available for discovery and execution by MCP clients