iseif/spring-ai-mcp-example

Spring AI MCP Server Example: Courses MCP

This repository contains a minimal Model Context Protocol (MCP) server built with Spring Boot and Spring AI. It exposes a few simple tools for listing, fetching, and adding “courses” over the MCP STDIO transport, making it easy to integrate with MCP-compatible clients like Claude Desktop, OpenAI MCP-compatible dev tools, Cursor, or the MCP Inspector.

Current date/time: 2025-08-09 15:52 (for reference)

What is inside

• Spring Boot console application (no web server) configured to run as an MCP server over STDIO.
• Spring AI ToolCallbacks automatically export annotated methods in CourseService as MCP tools.
• Three example tools:
  • sd_get_courses: List all available courses.
  • sd_get_course: Get a course by its title.
  • sd_add_course: Add a new course given a Course object with title and url.

Key classes/files:

• src/main/java/dev/iseif/mcpspringai/McpSpringAiApplication.java — Spring Boot entry point.
• src/main/java/dev/iseif/mcpspringai/AppConfiguration.java — Registers CourseService as ToolCallbacks.
• src/main/java/dev/iseif/mcpspringai/CourseService.java — Implements the tools via @Tool annotations.
• src/main/java/dev/iseif/mcpspringai/Course.java — Record type for courses.
• src/main/resources/application.properties — MCP server name/version and STDIO-friendly logging.

Prerequisites

• Java 17+ (recommended to match your Maven/target settings).
• Maven 3.9+ (or use the included Maven wrapper).
• An MCP-compatible client if you want to integrate (optional):
  • Claude Desktop (supports MCP providers via a JSON config).
  • MCP Inspector: npx @modelcontextprotocol/inspector.
  • Other MCP-capable tools/editors.

Build

On Windows PowerShell (using the wrapper):

• ./mvnw.cmd -q -DskipTests package

Or if Maven is installed:

• mvn -q -DskipTests package

This produces a runnable JAR under target/.

Run (STDIO MCP Server)

This app is a pure console process designed for STDIO transport. It must not print banners or normal console logs (already configured).

Run it directly:

• java -jar target/mcp-spring-ai-*.jar

The process will wait on STDIN/STDOUT for MCP JSON-RPC messages from your client.

Configuration defaults (see src/main/resources/application.properties):

spring.application.name=mcp-spring-ai
spring.main.web-application-type=none
spring.ai.mcp.server.name=courses-mcp
spring.ai.mcp.server.version=1.0.0

# Required for STDIO transport
spring.main.banner-mode=off
logging.pattern.console=

Tools (Capabilities)

These tools are discovered by Spring AI from CourseService:

1. sd_get_courses

• Description: List all available courses.
• Parameters: none
• Returns: List<Course> where Course is { title: string, url: string }.

2. sd_get_course

• Description: Get course by title.
• Parameters:
  • title (string) — exact course title match.
• Returns: Course | null.

3. sd_add_course

• Description: Add a new course.
• Parameters:
  • course (object) — { title: string, url: string }.
• Returns: void (no content).

Initial data (loaded at startup):

• Spring Boot — https://spring.io/projects/spring-boot
• Spring — https://spring.io/projects/spring-framework
• Spring Security — https://spring.io/projects/spring-security
• Spring Data JPA — https://spring.io/projects/spring-data-jpa

Using with MCP Clients

1) MCP Inspector (great for testing)

If you have Node.js:

• Install and run: npx @modelcontextprotocol/inspector
• Add a new server (STDIO):
  • Command: java
  • Args: -jar, F:/development/repos/mcp-spring-ai/target/mcp-spring-ai-<version>.jar
  • Working directory: the project root (or wherever the JAR is located)
• Connect and you should see the courses-mcp server and its three tools.

2) Claude Desktop

Edit (or create) your Claude Desktop MCP config file (varies by OS). For Windows, it’s usually at:

%APPDATA%/Claude/claude_desktop_config.json

Add a provider entry similar to:

{
  "mcpServers": {
    "courses-mcp": {
      "command": "java",
      "args": [
        "-jar",
        "F:/development/repos/mcp-spring-ai/target/mcp-spring-ai-<version>.jar"
      ],
      "env": {}
    }
  }
}

Restart Claude Desktop. It should discover the courses-mcp server and allow the model to call the tools.

3) Other MCP-compatible tools

Consult your client’s documentation for configuring a “stdio” MCP server. The key is to launch:

• java -jar path/to/mcp-spring-ai-<version>.jar

and hook up STDIN/STDOUT.

Troubleshooting

• Blank console output is expected. The server communicates via STDIO JSON-RPC. Do not enable normal console logs.
• If you see Spring Boot banners or logs, ensure in application.properties:
  • spring.main.banner-mode=off
  • logging.pattern.console= (empty)
• If the client cannot find tools:
  • Ensure AppConfiguration is picked up (it is in the same package tree).
  • Ensure you built the project and are running the built JAR, not an old version.
• Java version mismatch:
  • Verify java -version is compatible with the project settings.

Development

• Run tests: ./mvnw.cmd test
• Rebuild fast: ./mvnw.cmd -q -DskipTests package
• Modify or add tools by annotating service methods with @Tool from Spring AI.

License

This project is provided as an example. Add your preferred license if you plan to redistribute.