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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

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

Workspace: tessl
Visibility: Public
Created: 2 months ago
Last updated: 2 months ago
Describes: pkg:maven/org.springframework.ai/spring-ai-starter-mcp-server@1.1.x
Publish Source: CLI
Badge