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

Configuration Guide

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

Complete guide to configuring Spring AI MCP Server.

Basic Configuration

Minimal Setup

spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.stdio=true
spring.ai.mcp.server.name=my-server

Production Setup

spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.name=production-mcp-server
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.instructions=Production MCP server with full capabilities
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.protocol=SSE
spring.ai.mcp.server.request-timeout=30s

# 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

# Change notifications
spring.ai.mcp.server.resource-change-notification=true
spring.ai.mcp.server.tool-change-notification=true
spring.ai.mcp.server.prompt-change-notification=true

Transport Configuration

STDIO Transport

For command-line tools:

spring.ai.mcp.server.stdio=true

No web server required.

SSE Transport (Default)

For web applications:

spring.ai.mcp.server.protocol=SSE
spring.ai.mcp.server.sse-endpoint=/sse
spring.ai.mcp.server.sse-message-endpoint=/mcp/message
server.port=8080

Streamable HTTP

For HTTP streaming:

spring.ai.mcp.server.protocol=STREAMABLE
spring.ai.mcp.server.streamable-http.mcp-endpoint=/mcp
server.port=8080

Stateless HTTP

For scalable deployments:

spring.ai.mcp.server.protocol=STATELESS
spring.ai.mcp.server.streamable-http.mcp-endpoint=/mcp
server.port=8080

Note: Stateless mode doesn't support:

Logging notifications
Progress tracking
Elicitation
Sampling

Server Types

Synchronous Server (Default)

spring.ai.mcp.server.type=SYNC

Use for:

Traditional Spring MVC applications
JDBC database access
Blocking operations

Asynchronous Server

spring.ai.mcp.server.type=ASYNC

Use for:

High concurrency requirements
Non-blocking I/O
Reactive database access (R2DBC)

Capability Configuration

Enable/disable specific capabilities:

# Enable all capabilities (default)
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

# Disable specific capabilities
spring.ai.mcp.server.capabilities.completion=false

Advanced Configuration

Custom Endpoints

spring.ai.mcp.server.base-url=/api/v1
spring.ai.mcp.server.sse-endpoint=/custom-sse
spring.ai.mcp.server.sse-message-endpoint=/custom-message

Timeouts

spring.ai.mcp.server.request-timeout=30s
spring.ai.mcp.server.keep-alive-interval=15s

Tool Response MIME Types

spring.ai.mcp.server.tool-response-mime-type.generateImage=image/png
spring.ai.mcp.server.tool-response-mime-type.generatePdf=application/pdf

Annotation Scanner

# Disable automatic annotation scanning
spring.ai.mcp.server.annotation-scanner.enabled=false

Tool Callback Converter

# Disable automatic ToolCallback conversion
spring.ai.mcp.server.tool-callback-converter=false

Environment-Specific Configuration

Using Spring Profiles

application-dev.properties:

spring.ai.mcp.server.stdio=true
spring.ai.mcp.server.name=dev-mcp-server
logging.level.org.springframework.ai.mcp=DEBUG

application-prod.properties:

spring.ai.mcp.server.protocol=SSE
spring.ai.mcp.server.name=prod-mcp-server
spring.ai.mcp.server.base-url=/api/v1
server.port=8080

Activate with:

java -jar app.jar --spring.profiles.active=prod

YAML Configuration

spring:
  ai:
    mcp:
      server:
        enabled: true
        stdio: false
        name: my-mcp-server
        version: 1.0.0
        type: SYNC
        protocol: SSE
        request-timeout: 30s
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true
        resource-change-notification: true
        tool-change-notification: true
        prompt-change-notification: true

Configuration Validation

Common Mistakes

❌ Wrong: Both STDIO and HTTP enabled

spring.ai.mcp.server.stdio=true
spring.ai.mcp.server.protocol=SSE

✅ Correct: Choose one transport

spring.ai.mcp.server.stdio=true
# OR
spring.ai.mcp.server.protocol=SSE

❌ Wrong: Stateless with full context

spring.ai.mcp.server.protocol=STATELESS
# Methods using McpSyncRequestContext won't work

✅ Correct: Use transport context for stateless

// Use McpTransportContext instead
public String tool(McpTransportContext context, String input) {
    // ...
}

Configuration Reference

For complete configuration options, see Configuration Properties Reference.

Next Steps

Error Handling Guide - Handle errors properly
Real-World Scenarios - See configurations in action
Architecture Reference - Understand the framework

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