CtrlK

Community Documentation Log in Get started

tessl/maven-org-springframework-ai--spring-ai-starter-mcp-server

Spring Boot Starter for building Model Context Protocol (MCP) servers with auto-configuration, annotation-based tool/resource/prompt definitions, and support for STDIO, SSE, and Streamable-HTTP transports

Overview

Eval results

Files

Quick Start Guide

Name: tessl/maven-org-springframework-ai--spring-ai-starter-mcp-server
Author: tessl

Get started with Spring AI MCP Server Starter in 5 minutes.

Prerequisites

Java 17 or higher
Maven or Gradle
Spring Boot 3.x

Step 1: Add Dependency

Maven

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server</artifactId>
</dependency>

Gradle

implementation 'org.springframework.ai:spring-ai-starter-mcp-server'

Step 2: Create Your First Tool

Create a simple calculator tool:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.stereotype.Component;
import org.springaicommunity.mcp.annotation.McpTool;
import org.springaicommunity.mcp.annotation.McpToolParam;

@SpringBootApplication
public class CalculatorMcpServer {
    public static void main(String[] args) {
        SpringApplication.run(CalculatorMcpServer.class, args);
    }
}

@Component
public class CalculatorTools {
    
    @McpTool(name = "add", description = "Add two numbers")
    public int add(
        @McpToolParam(description = "First number", required = true) int a,
        @McpToolParam(description = "Second number", required = true) int b) {
        return a + b;
    }
    
    @McpTool(name = "multiply", description = "Multiply two numbers")
    public int multiply(
        @McpToolParam(description = "First number", required = true) int a,
        @McpToolParam(description = "Second number", required = true) int b) {
        return a * b;
    }
}

Step 3: Configure the Server

Create application.properties:

# Enable STDIO transport for command-line usage
spring.ai.mcp.server.stdio=true

# Server metadata
spring.ai.mcp.server.name=calculator-server
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.instructions=A simple calculator MCP server

Step 4: Run the Server

mvn spring-boot:run

Or build and run:

mvn clean package
java -jar target/calculator-mcp-server.jar

Step 5: Test Your Server

The server is now running and can be connected to by MCP clients via STDIO.

Testing with Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "calculator": {
      "command": "java",
      "args": ["-jar", "/path/to/calculator-mcp-server.jar"]
    }
  }
}

Next: Add More Capabilities

Add a Resource

@Component
public class ConfigResource {
    
    @McpResource(
        uri = "config://{key}",
        name = "Configuration",
        description = "Get configuration value")
    public String getConfig(String key) {
        return switch(key) {
            case "version" -> "1.0.0";
            case "name" -> "Calculator Server";
            default -> "Unknown config key";
        };
    }
}

Add Progress Tracking

@McpTool(name = "factorial", description = "Calculate factorial with progress")
public String factorial(
        McpSyncRequestContext context,
        @McpToolParam(description = "Number", required = true) int n) {
    
    context.info("Starting factorial calculation");
    context.progress(0);
    
    long result = 1;
    for (int i = 1; i <= n; i++) {
        result *= i;
        context.progress((i * 100) / n);
    }
    
    context.info("Calculation complete");
    return "Factorial of " + n + " is " + result;
}

Add Error Handling

@McpTool(name = "divide", description = "Divide two numbers")
public CallToolResult divide(
        @McpToolParam(description = "Numerator", required = true) double a,
        @McpToolParam(description = "Denominator", required = true) double b) {
    
    if (b == 0) {
        return CallToolResult.builder()
            .addTextContent("Error: Division by zero is not allowed")
            .isError(true)
            .build();
    }
    
    double result = a / b;
    return CallToolResult.builder()
        .addTextContent("Result: " + result)
        .build();
}

Common Transport Configurations

STDIO (Command-line)

spring.ai.mcp.server.stdio=true

SSE (Web-based)

spring.ai.mcp.server.stdio=false
spring.ai.mcp.server.protocol=SSE
server.port=8080

Streamable HTTP

spring.ai.mcp.server.protocol=STREAMABLE
server.port=8080

Stateless (Scalable)

spring.ai.mcp.server.protocol=STATELESS
server.port=8080

Troubleshooting

Tool Not Discovered

Problem: Your tool isn't showing up.

Solution: Ensure:

Class has @Component annotation
Method is public
Annotation scanner is enabled (default)

Connection Issues

Problem: Client can't connect.

Solution:

For STDIO: Check command path and arguments
For HTTP: Verify port is available and not blocked
Check server logs for startup errors

Schema Generation Errors

Problem: Parameter schema not generated.

Solution: Use supported types:

Primitives: int, double, boolean, String
POJOs with getters
Or use CallToolRequest for dynamic schemas

Next Steps

Configuration Guide - Explore all configuration options
Error Handling Guide - Learn best practices
Real-World Scenarios - See production examples
Architecture Reference - Understand the framework

tessl i tessl/maven-org-springframework-ai--spring-ai-starter-mcp-server@1.1.0