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

Spring AI MCP Server Starter

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

Spring Boot starter for building Model Context Protocol (MCP) servers with auto-configuration, annotation-based definitions, and multiple transport protocols.

Quick Reference

Aspect	Details
Package	`org.springframework.ai:spring-ai-starter-mcp-server`
Type	Maven Spring Boot Starter
Language	Java
Protocols	STDIO, SSE, Streamable-HTTP, Stateless
Server Types	Synchronous (SYNC), Asynchronous (ASYNC)

Installation

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

Quick Start

1. Basic Tool Definition

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

@Component
public class MyTools {
    @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;
    }
}

2. Basic Configuration

spring.ai.mcp.server.stdio=true
spring.ai.mcp.server.name=my-mcp-server
spring.ai.mcp.server.version=1.0.0

→ Complete Quick Start Guide

Core Concepts

Server Capabilities

Tools: Executable functions with JSON schema parameters
Resources: URI-addressable data with template support
Prompts: Reusable prompt templates with arguments
Completions: Auto-completion for prompt arguments

Annotation Types

Annotation	Purpose	Example
`@McpTool`	Define executable tool	`@McpTool(name = "calc")`
`@McpResource`	Define resource	`@McpResource(uri = "config://{key}")`
`@McpPrompt`	Define prompt template	`@McpPrompt(name = "greeting")`
`@McpComplete`	Define completion	`@McpComplete(prompt = "city")`

Transport Protocols

Protocol	Use Case	Configuration
STDIO	CLI tools	`spring.ai.mcp.server.stdio=true`
SSE	Web apps (default)	`spring.ai.mcp.server.protocol=SSE`
Streamable	HTTP streaming	`spring.ai.mcp.server.protocol=STREAMABLE`
Stateless	Scalable deployments	`spring.ai.mcp.server.protocol=STATELESS`

Server Types

Type	Execution Model	Return Types
SYNC	Blocking operations	Primitives, Objects, MCP types
ASYNC	Reactive operations	`Mono<T>`, `Flux<T>`

Essential Imports

// Annotations
import org.springaicommunity.mcp.annotation.McpTool;
import org.springaicommunity.mcp.annotation.McpToolParam;
import org.springaicommunity.mcp.annotation.McpResource;
import org.springaicommunity.mcp.annotation.McpPrompt;
import org.springaicommunity.mcp.annotation.McpArg;

// Context
import org.springaicommunity.mcp.server.McpSyncRequestContext;
import org.springaicommunity.mcp.server.McpAsyncRequestContext;

// Schema Types
import org.springaicommunity.mcp.schema.McpSchema.*;

// Spring
import org.springframework.stereotype.Component;
import org.springframework.context.annotation.Bean;

Common Patterns

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")
            .isError(true)
            .build();
    }
    
    return CallToolResult.builder()
        .addTextContent("Result: " + (a / b))
        .build();
}

Progress Tracking

@McpTool(name = "process", description = "Process with progress")
public String process(McpSyncRequestContext context, 
                      @McpToolParam(description = "Data") String data) {
    context.info("Starting");
    context.progress(0);
    
    // Work...
    context.progress(50);
    
    // More work...
    context.progress(100);
    return "Done";
}

Resource with URI Template

@McpResource(
    uri = "config://{key}",
    name = "Configuration",
    description = "Get config value")
public String getConfig(String key) {
    return configService.get(key);
}

Configuration Quick Reference

# Server basics
spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.name=mcp-server
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.type=SYNC  # or ASYNC

# Transport
spring.ai.mcp.server.stdio=false
spring.ai.mcp.server.protocol=SSE  # SSE, STREAMABLE, STATELESS

# Capabilities
spring.ai.mcp.server.capabilities.tool=true
spring.ai.mcp.server.capabilities.resource=true
spring.ai.mcp.server.capabilities.prompt=true
spring.ai.mcp.server.capabilities.completion=true

# Timeouts
spring.ai.mcp.server.request-timeout=20s

Troubleshooting Quick Fixes

Problem	Solution
Tool not discovered	Ensure class is `@Component` and method is public
Connection fails	Check transport config and port availability
Schema generation fails	Use supported types or explicit `CallToolRequest`
Context unavailable	Verify stateful protocol (not STATELESS)

Documentation Structure

Guides

Quick Start Guide - Step-by-step setup and first tool
Configuration Guide - Complete configuration options
Error Handling Guide - Best practices for errors

Examples

Real-World Scenarios - Production use cases
Edge Cases - Advanced scenarios and solutions
Integration Patterns - Common integration approaches

Reference

Server Annotations - Complete annotation reference
Architecture - Framework architecture details
Configuration Properties - All configuration options
Request Context - Context API reference
MCP Schema Types - Protocol type definitions
Tool Callbacks - Programmatic tool registration
Programmatic Registration - Low-level bean registration
Utilities - Helper classes and methods
Client Integration - Client-side components
Client Customizers - Client configuration
Client Handler Annotations - Client-side handlers
Filters and Converters - Tool filtering and naming
Context and Events - Connection metadata and events
Native Image Support - GraalVM native compilation

Key Features

✅ Automatic Discovery: Annotated methods auto-registered
✅ JSON Schema Generation: Parameters auto-converted to schemas
✅ Spring Boot Integration: Full auto-configuration and DI
✅ Change Notifications: Dynamic tool/resource/prompt updates
✅ Context Access: Logging, progress, elicitation, sampling
✅ Tool Conversion: ToolCallback beans → MCP specifications
✅ Multiple Return Types: Primitives, objects, reactive types

Next Steps

New to MCP? → Start with Quick Start Guide
Need configuration help? → See Configuration Guide
Building complex tools? → Check Real-World Scenarios
API details? → Browse Reference Documentation

Support Resources

Spring AI Documentation: https://docs.spring.io/spring-ai/reference/
MCP Specification: https://modelcontextprotocol.io/
GitHub Repository: https://github.com/spring-projects/spring-ai

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