Dan Iftodi

The Model Context Protocol (MCP) is an open standard introduced by Anthropic in November 2024. It defines a common way for AI models, like large language models, to connect and exchange data with external tools and systems. Often called “the USB‑C of AI apps,” MCP acts as a universal bridge, allowing AI assistants to read files, run functions, and share contextual information in a consistent way.

Spoiler: at the end, you’ll get a response like this from the AI agent:

Let’s get started.

In this article, we’ll walk through building a simple MCP server with Java and Spring AI. Spring AI makes this process much easier by taking care of the protocol implementation, so we can focus on the actual functionality.

An MCP server can communicate with an agent either over STDIO or via Streamable HTTP. In our example, we’ll build one using STDIO. If you want to expose your MCP server to external agents, Streamable HTTP is usually a better choice.

Every MCP server needs to define and expose tools—functions or operations that the agent can call. Once we’ve built the server, we’ll register it so that the agent can discover and use these tools.

We will build an MCP server that is used as a registry for users, it will expose these tools:

• getAllUsers
• getUser
• createUser
• userExists

By the end of this tutorial, we’ll have a simple console application that looks a lot like the ones we used to build back in university—except this one will speak JSON messages over the MCP protocol.

Let’s get started:

1. Open Spring Initializr.
2. Add the Model Context Protocol Server AI dependency.
3. Generate and download the project.

Next, let’s define our User model. You can find an example implementation here:
User.java

We’ll also need a simple UserService to manage users. Example implementation:
UserService.java

If we were building a traditional web application, at this point we would create a REST layer with controllers to expose our endpoints.
When building an MCP server, the approach is similar—but instead of REST endpoints, we expose tools.

Here’s what exposing a tool looks like:

@Tool(name = "getAllUsers",
    description = "Retrieves all users information. Returns user details including ID, name, email, and status."
    )
public List<User> getAllUsers() {
    return new ArrayList<>(userService.getAllUsers().values());
}

Here is the implementation of our UserMcpController:
UserMcpController.java

At this point, we’ve almost completed our MCP server implementation. There’s just one more step: we need to create a bean of type ToolCallbackProvider. This bean will register the tools we defined so the MCP server can expose them to agents.

Here’s how to define it:

@Configuration
public class McpConfiguration {

    @Bean
    public ToolCallbackProvider methodToolCallbackProvider(UserMcpController mcpController) {
        return MethodToolCallbackProvider
            .builder()
            .toolObjects(mcpController)
            .build();
    }
}

A bean of type ToolCallbackProvider is used internally by Spring AI when building the MCP tool. Its purpose is to connect the agent with the tool, enabling communication between them. Without this bean, the MCP server wouldn’t be able to expose the tool’s functionality to the agent.

We’ve built our application using:

./gradlew bootJar

Now it’s time to register our MCP server with an agent. To do this, we need to define an mcp.json file. You can place it in the same folder where you’ll run the server, or globally in:

~/.cursor/mcp.json

(In this example, we’re using cursor-agent.)

Here’s an example structure for mcp.json:

{
  "mcpServers": {
    "spring-ai": {
      "command": "java -jar  <ABSOLUTE_PATH>/spring-mcp-0.0.1-SNAPSHOT.jar",
      "transport": "stdio"
    }
  }
}

It’s time to use it:

Github repository: https://github.com/daniftodi/mcp-spring-ai