Spring AI - MCP Server

Posted on In ,

Model Context Protocol (MCP) Servers are programs that expose specific capabilities to AI applications through standardized protocol interfaces. Each server provides focused functionality for a particular domain.

Dependency

For STDIO MCP Server, add the following dependency to your pom.xml file:

1
2
3
4
<dependency>
	<groupId>org.springframework.ai</groupId>
	<artifactId>spring-ai-starter-mcp-server</artifactId>
</dependency>

WebMVC MCP Server, add the following dependency to your pom.xml file:

1
2
3
4
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

For WebFlux MCP Server, add the following dependency to your pom.xml file:

1
2
3
4
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

MCP Server protocols:

  • STDIO: Communication via stdin and stdout. To enable the STDIO set spring.ai.mcp.server.stdio=true
  • SSE: Server-sent events protocol for real-time updates. The server operates as an independent process that can handle multiple client connections.
  • Streamable-HTTP - The Streamable HTTP transport allows MCP servers to operate as independent processes that can handle multiple client connections using HTTP POST and GET requests, with optional Server-Sent Events (SSE) streaming for multiple server messages. It replaces the SSE transport. To enable the STREAMABLE protocol, set spring.ai.mcp.server.protocol=STREAMABLE.
  • Stateless - Stateless MCP servers are designed for simplified deployments where session state is not maintained between requests. They are ideal for microservices architectures and cloud-native deployments. To enable the STATELESS protocol, set spring.ai.mcp.server.protocol=STATELESS.

The MCP Server Boot Starter allows servers to expose tools, resources, and prompts to clients.

Streamable MCP Server

The Streamable MCP Server is a new protocol that allows MCP servers to operate as independent processes that can handle multiple client connections using HTTP POST and GET requests, with optional Server-Sent Events (SSE) streaming for multiple server messages.

application.properties:

1
2
3
spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.name=todo-list-mcp
spring.ai.mcp.server.protocol=STREAMABLE

Create a tool service by annotating a method with @Tool. The method can return any type of data, and the MCP server will handle the serialization and communication with the AI application. Tool descriptions can be provided using the description attribute of the @Tool annotation, which will be visible to AI applications when they query the server for available tools. In this example, we create a simple tool that returns a list of todo items:

1
2
3
4
5
6
7
8
9
10
11
12
13
public record TodoItem(int id, String description, boolean completed){
}

@Service
public class TodoListService {
    @Tool(description = "Get a list of todo items")
    public List<TodoItem> getTodoItemList() {
        return List.of(
            new TodoItem(1, "laundry", false),
            new TodoItem(2, "Cook Spaghetti", true)
        );
    }
}

Register the tool with the MCP server bean. The MethodToolCallbackProvider can be used to automatically register all methods annotated with @Tool in the specified service class:

1
2
3
4
@Bean
public ToolCallbackProvider myTools(TodoListService todoListService) {
	return MethodToolCallbackProvider.builder().toolObjects(todoListService).build();
}

You should see the following log when the server starts successfully with the tool registered:

1
2
o.s.a.m.s.c.a.McpServerAutoConfiguration : Enable tools capabilities, notification: true
o.s.a.m.s.c.a.McpServerAutoConfiguration : Registered tools: 1

add the server to mcp.json file. For VS Code in iOS, the file should be in ~/Library/Application\ Support/Code/User/mcp.json. The
default url for a streamable MCP server is http://localhost:8080/mcp.

1
2
3
4
5
6
7
{
	"servers": {
		"todo-list-mcp": {
			"url": "http://localhost:8080/mcp"
		}
    }
}

Now you can ask the tool in VS Code with the following prompt:

1
what is in the todo list?

Answer from Copilot will be:

1
2
3
4
Todo list has 2 items:

1: laundry (not completed)
2: Cook Spaghetti (completed)

SSE configuration is very similar to streamable, but the endpoint is http://localhost:8080/mcp.

Reference