The Model Context Protocol (MCP) allows AI models to securely access external data and tools. Let us delve into understanding how the Spring AI model, context handling, and the MCP (Model Context Protocol) work together.
1. What is Spring AI?
Spring AI is an extension of the popular Spring Boot framework that allows developers to integrate large language models (LLMs) and AI capabilities directly into their applications. It simplifies building intelligent features such as chatbots, recommendation engines, and natural language understanding within Spring-based systems.
1.1 What is MCP?
MCP (Model Context Protocol) is an open protocol that defines a standardized way for applications to connect Large Language Models (LLMs) with data sources, tools, and external applications. Much like how USB-C provides a universal connector for physical devices, MCP provides a universal “connector” for digital interactions between models and their environment. By serving as a bridge, MCP makes it easier to build intelligent agents, orchestrate complex workflows, and enable LLMs to interact meaningfully with the outside world. It ensures interoperability, flexibility, and a vendor-neutral approach that allows innovation without lock-in.
1.1.1 Key Features and Benefits of MCP
- Pre-built integrations: Offers ready-to-use connections so that your LLM can immediately access common services, APIs, and databases.
- Standardized interface: Provides a common language for developers to build custom integrations without reinventing the wheel.
- Open protocol: Anyone can implement MCP, ensuring transparency, community-driven improvements, and wide adoption.
- Context continuity: Enables seamless switching between applications while preserving user context, improving workflows and user experiences.
- Extensibility: Developers can create new custom connectors without affecting compatibility with existing integrations.
- Security-aware design: Enforces controlled access to data and tools, ensuring a safer environment for production-ready applications.
- Future-proof foundation: Designed to evolve alongside rapidly developing AI ecosystems, reducing integration complexity over time.
MCP essentially acts as the “plug-and-play” system for AI capabilities, helping LLMs not just answer questions but take actions, call APIs, query databases, and interact with business or personal tools in a structured manner. Learn more about MCP at the official website: Model Context Protocol.
2. Code Example (MCP Server)
This section demonstrates how to build an MCP Server using Spring Boot and Spring AI. The server exposes a tool named getCurrentWeather that returns mock weather data, which can be consumed by the MCP Client.
2.1 Add Dependencies (pom.xml)
Add the following dependencies to your pom.xml to include Spring Boot and the Spring AI MCP Server starter.
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server</artifactId>
<version>your__latest__jar_version</version>
</dependency>
</dependencies>
2.2 Creating the configuration YAML
The following YAML configures the MCP Server to run on port 8080.
server:
port: 8080
spring:
application:
name: weather-mcp-server
2.3 Create a POJO Class
The WeatherData POJO is used to represent weather data returned by the server.
package com.example.mcpserver;
public class WeatherData {
private String city;
private double temperature;
private String description;
// Getters, setters, and constructors omitted for brevity
}
2.4 Create a Tool Service Class
This service defines the MCP tool getCurrentWeather and provides mock data for demonstration.
package com.example.mcpserver;
import org.springframework.ai.mcp.server.tool.McpTool;
import org.springframework.stereotype.Service;
import java.util.Map;
@Service
public class WeatherToolService {
@McpTool(name = "getCurrentWeather", description = "Get current weather for a given city")
public WeatherData getCurrentWeather(Map args) {
String city = (String) args.get("city");
// Mock response
return new WeatherData(city, 15.5, "Cloudy with light rain");
}
}
The WeatherToolService class defines a simple tool for retrieving current weather information using the @McpTool annotation, which registers the method as an MCP-compatible tool named “getCurrentWeather” with a description indicating its purpose. Inside the method getCurrentWeather, it accepts a map of arguments, extracts the value associated with the key "city", and then returns an instance of WeatherData that contains the city name, a mock temperature value of 15.5 degrees, and the weather condition description “Cloudy with light rain”. Essentially, this class demonstrates how to expose a function as an MCP tool that can provide structured weather information for a requested city.
2.5 Create a Main Class
The McpServerApplication class is the entry point for the MCP Server application.
package com.example.mcpserver;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class McpServerApplication {
public static void main(String[] args) {
SpringApplication.run(McpServerApplication.class, args);
}
}
2.6 Code Run and Demo
To run the server, navigate to the project root and execute: mvn clean install && mvn spring-boot:run. The server will start on http://localhost:8080 and expose the tool getCurrentWeather for the MCP Client to call.
3. Code Example (MCP Client)
3.1 Add Dependencies (pom.xml)
This section provides a complete example of integrating an MCP client with a Spring Boot application, including adding required dependencies, configuring application settings, defining data and service classes, and running the application to test communication with the MCP server.
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-client</artifactId>
<version>your__latest__jar_version</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
</dependencies>
3.2 Creating the configuration YAML
Next, configure your Spring Boot application to enable the MCP client and specify its connection details. The following YAML sets the server port to 8081, enables the MCP client, defines its name, version, and type, and configures the connection to the MCP server running at http://localhost:8080.
server:
port: 8081
spring:
ai:
mcp:
client:
enabled: true
name: weather-mcp-client
version: 1.0.0
type: SYNC
request-timeout: 30s
sse:
connections:
weather-server:
url: http://localhost:8080
3.3 Create a POJO Class
The following POJO class WeatherData represents the weather information retrieved from the MCP server. It includes fields for city, temperature, and description, along with standard getters, setters, and constructors.
package com.example.mcpclient;
public class WeatherData {
private String city;
private double temperature;
private String description;
// Getters, setters, and constructors omitted for brevity
}
3.4 Create a Service Class
The WeatherQueryService class handles communication with the MCP server through the McpSyncClient. It defines a method getCurrentWeather that sends a request to the MCP tool with the specified city name and returns a WeatherData object containing the response.
package com.example.mcpclient;
import org.springframework.ai.mcp.client.McpSyncClient;
import org.springframework.stereotype.Service;
import org.springframework.beans.factory.annotation.Autowired;
@Service
public class WeatherQueryService {
private final McpSyncClient mcpSyncClient;
@Autowired
public WeatherQueryService(McpSyncClient mcpSyncClient) {
this.mcpSyncClient = mcpSyncClient;
}
public WeatherData getCurrentWeather(String city) {
// Arguments as per MCP tool definition
var args = new java.util.HashMap<String, Object>();
args.put("city", city);
// 'getCurrentWeather' must match MCP server tool name
Object result = mcpSyncClient.invokeTool("getCurrentWeather", args);
// Assuming result maps to WeatherData
if (result instanceof WeatherData weatherData) {
return weatherData;
} else {
// handle error or mapping
return null;
}
}
}
The WeatherQueryService class is a Spring-managed service that uses an injected McpSyncClient to query weather information via the MCP protocol. Its constructor, annotated with @Autowired, ensures that an instance of McpSyncClient is automatically provided. The method getCurrentWeather takes a city name as input, builds an argument map with the key "city", and then invokes the MCP server tool named "getCurrentWeather" through mcpSyncClient.invokeTool. The returned object is checked to ensure it is of type WeatherData; if so, it is returned, otherwise the method returns null. This class essentially acts as a client-side service layer that communicates with the MCP tool to retrieve structured weather data for a given city.
3.5 Create a Main Class
The McpClientApplication class serves as the entry point of the Spring Boot application and exposes a REST API endpoint at /weather/{city}. It uses WeatherQueryService to fetch weather data from the MCP server and returns it as a response.
package com.example.mcpclient;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
@SpringBootApplication
@RestController
public class McpClientApplication {
private final WeatherQueryService weatherQueryService;
public McpClientApplication(WeatherQueryService weatherQueryService) {
this.weatherQueryService = weatherQueryService;
}
@GetMapping("/weather/{city}")
public WeatherData getWeather(@PathVariable String city) {
return weatherQueryService.getCurrentWeather(city);
}
public static void main(String[] args) {
SpringApplication.run(McpClientApplication.class, args);
}
}
3.6 Code Run and Demo
To run the application and test the integration, follow these steps: Start the MCP Server – ensure that your MCP server (e.g., weather-server) is running at http://localhost:8080. Build and Run the Spring Boot Application – from the project root, run mvn clean install && mvn spring-boot:run.
Access the REST Endpoint – once the application is running on http://localhost:8081, test it using
curl http://localhost:8081/weather/London.
{
"city": "London",
"temperature": 15.5,
"description": "Cloudy with light rain"
}
4. Integrating LLM with Spring AI and MCP
To showcase tool calling via an LLM, use Spring AI’s native support for Ollama and function tool invocation. Spring AI now supports Ollama’s “tool calling” feature, enabling LLMs to reason on input and automatically decide when to call external tools such as getCurrentWeather. This setup lets you leverage the MCP weather tool within your conversational workflow.
4.1 Add Dependencies (pom.xml)
Extend your pom.xml with Spring AI Ollama dependencies:
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-ollama</artifactId>
<version>your__latest__jar_version</version>
</dependency>
</dependencies>
You’ll also need Ollama running locally and an LLM model (like Llama 3 or Mistral) pulled using Ollama’s CLI.
4.2 Configuration
Add these to your application.yml to configure Spring AI to use Ollama and enable tool support:
spring:
ai:
ollama:
enabled: true
model: llama3
base-url: http://localhost:11434
mcp:
client:
enabled: true
connections:
weather-server:
url: http://localhost:8080
This sets up the local LLM endpoint and connects your MCP client to the weather tool server.
4.3 LLM Service with Tool Delegation
Create a service method to handle conversational prompts. When the user asks for weather info, the conversation context will prompt the LLM to call the MCP weather tool. With Ollama’s tool calling, Spring AI automatically routes requests like “What’s the weather in Paris?” to the MCP weather API and returns the result:
@Service
public class ChatService {
private final AiChatClient aiChatClient; // Spring AI
@Autowired
public ChatService(AiChatClient aiChatClient) {
this.aiChatClient = aiChatClient;
}
public String chat(String prompt) {
AiChatResponse response = aiChatClient.chat(prompt);
return response.getContent();
}
}
When the prompt matches the tool’s schema (city + weather intent), the LLM will use Spring AI’s integrations to query getCurrentWeather via MCP, returning structured weather data in the LLM’s reply.
4.4 Endpoint Example
For demonstration, create a REST endpoint where users can query the LLM:
@RestController
public class AiController {
@Autowired
private ChatService chatService;
@GetMapping("/ask")
public String ask(@RequestParam String prompt) {
return chatService.chat(prompt);
}
}
A call such as:
curl "http://localhost:8081/ask?prompt=What's the weather in London?"
will return a response generated by the LLM.
{
"city": "London",
"temperature": 15.5,
"description": "Cloudy with light rain"
}
Note: Once the LLM identifies a weather-related query, Spring AI routes the request to the MCP tool, which provides up-to-date weather information in the response.
5. Conclusion
This tutorial demonstrates building an MCP-enabled system with Spring Boot and Spring AI, covering both server and client perspectives for secure tool exposure and seamless consumption. The setup enables conversational agents to interpret user queries and dynamically invoke MCP tools, such as retrieving live weather data, through Spring AI’s clean APIs and flexible configuration. Together, MCP and Spring AI provide a solid foundation for intelligent, agentic applications, offering interoperability, dynamic tool access, and support for custom or open-source LLMs.
