Product MCP Server — Spring Boot 4 + Spring AI

A small but complete Model Context Protocol (MCP) server built with Spring Boot 4 and Spring AI. It exposes a fictional product & order management app as MCP tools that any MCP-capable AI agent (Claude Desktop, Claude Code, Cursor, VS Code, …) can call to read and change data.

It is the sample project for the Tucanoo tutorial: "Building an MCP Server in Java: Connecting Your Spring Boot App to AI Agents" → https://tucanoo.com/building-an-mcp-server-in-java-connecting-your-spring-boot-app-to-ai-agents/

No LLM, no API key, no database required. An MCP server doesn't run a model — the connecting agent brings the AI. Data is held in memory and seeded at startup.

What it exposes

Tools

Plus one resource — catalog://products/{sku} — returning a product summary, to demonstrate the MCP resource primitive alongside tools.

Requirements

• Java 17+ (built and tested on Java 25)
• Node.js — only to run the MCP Inspector for testing
• An MCP client to connect to (e.g. Claude Desktop for stdio, Claude Code for HTTP)

Versions

• Spring Boot 4.0.6
• Spring AI 2.0.0-RC1 — the line that targets Boot 4. It is a release candidate (pre-GA); the version is pinned in build.gradle. Move to 2.0.0 GA when it ships.

Build

./gradlew build

This produces build/libs/product-mcp-server-0.0.1-SNAPSHOT.jar.

Two transports, one starter

This project uses the single spring-ai-starter-mcp-server-webmvc starter for both transports; a Spring profile picks which one runs.

1. stdio (the AI client launches the jar)

stdio carries the protocol over stdin/stdout, so the app must not print anything else. The stdio profile turns off the web server, the banner, and console logging (logs go to a file instead):

java -jar build/libs/product-mcp-server-0.0.1-SNAPSHOT.jar --spring.profiles.active=stdio

You normally don't run this yourself — the AI client does (see Claude Desktop below).

2. Streamable HTTP (a long-running web server)

java -jar build/libs/product-mcp-server-0.0.1-SNAPSHOT.jar --spring.profiles.active=http
# MCP endpoint: http://localhost:8080/mcp

(Use --server.port=8081 if 8080 is taken.)

Test it with the MCP Inspector

stdio:

# list tools
SPRING_PROFILES_ACTIVE=stdio npx @modelcontextprotocol/inspector --cli \
  java -jar build/libs/product-mcp-server-0.0.1-SNAPSHOT.jar --method tools/list

# call a tool
SPRING_PROFILES_ACTIVE=stdio npx @modelcontextprotocol/inspector --cli \
  java -jar build/libs/product-mcp-server-0.0.1-SNAPSHOT.jar \
  --method tools/call --tool-name search_products --tool-arg query=headphones

HTTP (start the server with the http profile first):

npx @modelcontextprotocol/inspector --cli http://localhost:8080/mcp --transport http --method tools/list

Run npx @modelcontextprotocol/inspector with no --cli for the web UI (it prints a session-token URL in the terminal — open that).

Connect Claude Desktop (stdio)

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "product-store": {
      "command": "java",
      "args": [
        "-jar",
        "/ABSOLUTE/PATH/TO/product-mcp-server/bui

... [View full README on GitHub](https://github.com/tucanoo/spring-mcp-server-tutorial#readme)