Spring AI – [ Building Protocol-Aware AI Agents with MCP ]

OVO

Working with LLMs often means you want more than just chat – you want agents that can reach out to tools, external data, and services in a standard, discoverable, reliable way.

Spring AI’s implementation of MCP (Model Context Protocol) helps you do just that.

What You Will Learn
  1. 1.What is MCP?
  2. 2.MCP Example Walkthrough
  3. 3. MCP Use Cases
  4. Conclusion

1.What is MCP?

MCP stands for Model Context Protocol.

It’s an open protocol designed to standardize how applications provide context to Large Language Models.

That includes:

  • Exposing tools and resources (APIs, files, etc.) to the model via a well-defined interface
  • Letting clients (i.e. your AI application) discover what tools/resources are available
  • Defining how prompts / templates / tool calls / resources are transported (via HTTP, SSE, STDIO, etc.)
  • Enabling interaction across language or service boundaries – you might have the server in one language or process, the client in another.

Spring AI adds support for MCP via Java SDK + Spring Boot starters/maven dependencies.

It also offers annotation-based helpers and auto-configuration to simplify the boilerplate.

2.MCP Example Walkthrough

Let’s build a simple example: a Weather + Math Tools MCP server and a client that uses them.

The server will expose two tools (weather lookup, simple add), the client will discover them and use them via Spring AI’s ChatClient + MCP.

2.1 MCP Server Example

A. Project setup

Add dependencies in your pom.xml:

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-mcp-server</artifactId>
  <version>1.1.0-M2</version> <!-- or latest -->
</dependency>
<!-- optionally for HTTP SSE or WebFlux transport -->
<dependency>
  <groupId>org.springframework.experimental</groupId>
  <artifactId>mcp-webflux-sse-transport</artifactId>
</dependency>

B. Expose tools via annotations

import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.stereotype.Component;

@Component
public class WeatherTools {
    @McpTool(description = "Get current weather for a city")
    public String getWeather(String city) {
        // In real, call a weather API
        if ("Paris".equalsIgnoreCase(city)) {
            return "Sunny, ~22°C in Paris.";
        }
        return "Weather info not available for " + city;
    }
}

@Component
public class MathTools {
   @McpTool(description = "Add two numbers")
   public int add(int a, int b) {
      return a + b;
   }
}

C. Configure server transport and host settings

In application.yml (or properties):

spring:
  ai:
    mcp:
      server:
        transport:
          streamable-http: 
            port: 8081
            path: /mcp
          # or choose SSE, STDIO etc.

D. Run the server

The server starts and listens on the transport (e.g. HTTP) for MCP clients.

It exposes available tools, handles discovery, execution etc.

2.2 MCP Client Example

A. Client dependencies

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-mcp-client</artifactId>
  <version>1.1.0-M2</version>
</dependency>

B. Client Configuration

In application.yml:

spring:
  ai:
    mcp:
      client:
        streamable-http:
          connections:
            weather-server:
              url: http://localhost:8081/mcp

C. Using tools in code

import org.springframework.ai.mcp.McpClient;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.tool.FunctionCallback;
import org.springframework.ai.mcp.spring.McpFunctionCallback;

@Component
public class MyAgentService {

  private final ChatClient chatClient;

  public MyAgentService(McpClient mcpClient, ChatClient.Builder chatBuilder) {
    // get tool descriptions from server
    FunctionCallback weatherCallback = new McpFunctionCallback(mcpClient, "getWeather");
    FunctionCallback addCallback = new McpFunctionCallback(mcpClient, "add");

    this.chatClient = chatBuilder
        .tools(weatherCallback, addCallback)
        .build();
  }

  public String ask(String question) {
    return chatClient.prompt()
                     .user(question)
                     .call()
                     .content();
  }
}

D. Run client and try

Example requests:

  • “What’s the weather in Paris?” – triggers getWeather tool
  • “Add 5 and 7 for me.” – triggers add tool

This is what happens :

  • Client starts, discovers tools from MCP Server via transport (HTTP/SSE etc.)
  • Client builds ChatClient with those tools exposed
  • User sends prompt (could be via UI or API)
  • ChatClient sends prompt to LLM along with tool metadata (tool schemas)
  • LLM decides if it should call a tool; sends function call back
  • The tool is executed by the server; result returned
  • LLM then composes final answer using tool result + prompt context

3. MCP Use Cases

Here are some practical use cases for MCP in Spring AI:

  • Local tool server: expose local file system, search documents, read local files
  • Microservices orchestration: your AI agent can call service APIs wrapped by MCP tools
  • Plugin architecture: external developers can provide new tools (MCP servers) that your client app can tap into without code changes
  • Hybrid models: using external servers for resource-intensive or sensitive tools (e.g. database queries, proprietary APIs), while keeping your core app lighter

Conclusion

Spring AI’s MCP support is a major step toward building robust, context-aware AI agents.

It standardizes how tools, prompts, and resources are exposed, discovered, and used.

Related Posts