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 Properties

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

Configuration properties for controlling MCP server behavior, capabilities, and transport settings.

Capabilities

Server Properties

Core server configuration properties.

// Property prefix: spring.ai.mcp.server

// Enable or disable the MCP server
spring.ai.mcp.server.enabled=true  // boolean, default: true

// Enable STDIO transport
spring.ai.mcp.server.stdio=false  // boolean, default: false

// Server name for identification
spring.ai.mcp.server.name=mcp-server  // String, default: "mcp-server"

// Server version
spring.ai.mcp.server.version=1.0.0  // String, default: "1.0.0"

// Optional instructions for clients
spring.ai.mcp.server.instructions=  // String, nullable

// Server type: SYNC or ASYNC
spring.ai.mcp.server.type=SYNC  // ApiType enum, default: SYNC

// Protocol: SSE, STREAMABLE, or STATELESS
spring.ai.mcp.server.protocol=SSE  // ServerProtocol enum, default: SSE

// Request timeout duration
spring.ai.mcp.server.request-timeout=20s  // Duration, default: 20 seconds

// Enable automatic conversion of Spring AI ToolCallbacks to MCP specs
spring.ai.mcp.server.tool-callback-converter=true  // boolean, default: true

Usage Example:

# application.properties
spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.stdio=true
spring.ai.mcp.server.name=my-calculator-server
spring.ai.mcp.server.version=2.0.0
spring.ai.mcp.server.instructions=A calculator server that provides basic arithmetic operations
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.protocol=SSE
spring.ai.mcp.server.request-timeout=30s

Or in YAML format:

# application.yml
spring:
  ai:
    mcp:
      server:
        enabled: true
        stdio: true
        name: my-calculator-server
        version: 2.0.0
        instructions: A calculator server that provides basic arithmetic operations
        type: SYNC
        protocol: SSE
        request-timeout: 30s

Capability Properties

Enable or disable specific MCP capabilities.

// Property prefix: spring.ai.mcp.server.capabilities

// Enable resource capabilities
spring.ai.mcp.server.capabilities.resource=true  // boolean, default: true

// Enable tool capabilities
spring.ai.mcp.server.capabilities.tool=true  // boolean, default: true

// Enable prompt capabilities
spring.ai.mcp.server.capabilities.prompt=true  // boolean, default: true

// Enable completion capabilities
spring.ai.mcp.server.capabilities.completion=true  // boolean, default: true

Usage Example:

# Disable resources, enable only tools and prompts
spring.ai.mcp.server.capabilities.resource=false
spring.ai.mcp.server.capabilities.tool=true
spring.ai.mcp.server.capabilities.prompt=true
spring.ai.mcp.server.capabilities.completion=false

Change Notification Properties

Control whether clients are notified of changes to tools, resources, and prompts.

// Property prefix: spring.ai.mcp.server

// Enable resource change notifications
spring.ai.mcp.server.resource-change-notification=true  // boolean, default: true

// Enable tool change notifications
spring.ai.mcp.server.tool-change-notification=true  // boolean, default: true

// Enable prompt change notifications
spring.ai.mcp.server.prompt-change-notification=true  // boolean, default: true

Usage Example:

# Enable all 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

Tool Response MIME Type

Specify MIME types for tool responses.

// Property prefix: spring.ai.mcp.server.tool-response-mime-type

// Map of tool name to MIME type
spring.ai.mcp.server.tool-response-mime-type.<toolName>=<mimeType>

Usage Example:

# Set MIME types for specific tools
spring.ai.mcp.server.tool-response-mime-type.generateImage=image/png
spring.ai.mcp.server.tool-response-mime-type.generatePdf=application/pdf
spring.ai.mcp.server.tool-response-mime-type.getJson=application/json

Annotation Scanner Properties

Control annotation scanning behavior.

// Property prefix: spring.ai.mcp.server.annotation-scanner

// Enable or disable annotation scanning
spring.ai.mcp.server.annotation-scanner.enabled=true  // boolean, default: true

Usage Example:

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

Client Configuration Properties

Configuration properties for MCP clients that connect to remote MCP servers.

Common Client Properties

Core configuration shared across all client transport types.

// Property prefix: spring.ai.mcp.client

// Enable or disable the MCP client
spring.ai.mcp.client.enabled=true  // boolean, default: true

// Client name for identification
spring.ai.mcp.client.name=spring-ai-mcp-client  // String, default: "spring-ai-mcp-client"

// Client version
spring.ai.mcp.client.version=1.0.0  // String, default: "1.0.0"

// Flag to indicate if the client should be initialized
spring.ai.mcp.client.initialized=true  // boolean, default: true

// Request timeout duration
spring.ai.mcp.client.request-timeout=20s  // Duration, default: 20 seconds

// Client type: SYNC or ASYNC
spring.ai.mcp.client.type=SYNC  // ClientType enum, default: SYNC

// Enable/disable root change notifications
spring.ai.mcp.client.root-change-notification=true  // boolean, default: true

// Enable/disable tool callback integration
spring.ai.mcp.client.toolcallback.enabled=true  // boolean, default: true

ClientType Enum:

SYNC - Synchronous (McpSyncClient) client (default)
ASYNC - Asynchronous (McpAsyncClient) client

Usage Example:

# application.properties
spring.ai.mcp.client.enabled=true
spring.ai.mcp.client.name=my-ai-client
spring.ai.mcp.client.type=ASYNC
spring.ai.mcp.client.request-timeout=30s
spring.ai.mcp.client.root-change-notification=true

STDIO Client Configuration

Configuration for connecting to MCP servers via standard input/output.

// Property prefix: spring.ai.mcp.client.stdio

// JSON resource containing server configurations
spring.ai.mcp.client.stdio.servers-configuration=classpath:mcp-servers.json

// Named STDIO connections
spring.ai.mcp.client.stdio.connections.<name>.command=  // String, required
spring.ai.mcp.client.stdio.connections.<name>.args=  // List<String>, optional
spring.ai.mcp.client.stdio.connections.<name>.env=  // Map<String, String>, optional

Usage Example:

# application.yml
spring:
  ai:
    mcp:
      client:
        stdio:
          connections:
            calculator-server:
              command: "node"
              args:
                - "/path/to/calculator-server/index.js"
              env:
                NODE_ENV: "production"
                DEBUG: "false"

            weather-server:
              command: "python"
              args:
                - "/path/to/weather-server/main.py"
                - "--port=8080"

Or using a JSON resource file:

# application.properties
spring.ai.mcp.client.stdio.servers-configuration=classpath:mcp-servers.json

// mcp-servers.json
{
  "mcpServers": {
    "calculator": {
      "command": "node",
      "args": ["/path/to/calculator/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "weather": {
      "command": "python",
      "args": ["/path/to/weather/main.py"]
    }
  }
}

SSE Client Configuration

Configuration for connecting to MCP servers via Server-Sent Events.

// Property prefix: spring.ai.mcp.client.sse

// Named SSE connections
spring.ai.mcp.client.sse.connections.<name>.url=  // String, required
spring.ai.mcp.client.sse.connections.<name>.sse-endpoint=  // String, optional (default: /sse)

Usage Example:

# application.yml
spring:
  ai:
    mcp:
      client:
        sse:
          connections:
            server1:
              url: "http://localhost:8080"
              # Uses default /sse endpoint

            mcp-hub:
              url: "http://localhost:3000"
              sse-endpoint: "/mcp-hub/sse/cf9ec4527e3c4a2cbb149a85ea45ab01"

            custom-server:
              url: "http://api.example.com"
              sse-endpoint: "/v1/mcp/events?token=abc123&format=json"

URL Splitting:

Split full URLs into base URL and SSE endpoint
Example: http://localhost:3000/mcp-hub/sse/token123
- url: http://localhost:3000
- sse-endpoint: /mcp-hub/sse/token123

Streamable HTTP Client Configuration

Configuration for connecting to MCP servers via Streamable HTTP transport.

// Property prefix: spring.ai.mcp.client.streamable-http

// Named Streamable HTTP connections
spring.ai.mcp.client.streamable-http.connections.<name>.url=  // String, required
spring.ai.mcp.client.streamable-http.connections.<name>.endpoint=  // String, optional

Usage Example:

# application.yml
spring:
  ai:
    mcp:
      client:
        streamable-http:
          connections:
            server1:
              url: "http://localhost:8080"
              endpoint: "/mcp/stream"

            server2:
              url: "http://otherserver:8081"
              endpoint: "/events"

# application.properties
spring.ai.mcp.client.streamable-http.connections.server1.url=http://localhost:8080
spring.ai.mcp.client.streamable-http.connections.server1.endpoint=/mcp/stream

SSE Properties

Configuration for Server-Sent Events transport (when using SSE protocol).

// Property prefix: spring.ai.mcp.server

// Custom SSE endpoint path
spring.ai.mcp.server.sse-endpoint=/sse  // String, default: "/sse"

// Custom SSE message endpoint path for client messages
spring.ai.mcp.server.sse-message-endpoint=/mcp/message  // String, default: "/mcp/message"

// Optional URL prefix for endpoints
spring.ai.mcp.server.base-url=  // String, optional

// Connection keep-alive interval
spring.ai.mcp.server.keep-alive-interval=  // Duration, default: null (disabled)

Usage Example:

# Custom SSE endpoints
spring.ai.mcp.server.sse-endpoint=/api/sse
spring.ai.mcp.server.sse-message-endpoint=/api/mcp/message
spring.ai.mcp.server.base-url=/api/v1
spring.ai.mcp.server.keep-alive-interval=10s

With base-url=/api/v1:

SSE endpoint: /api/v1/sse
Message endpoint: /api/v1/mcp/message

Streamable HTTP Properties

Configuration for Streamable HTTP transport (when using STREAMABLE or STATELESS protocol).

// Property prefix: spring.ai.mcp.server.streamable-http

// MCP endpoint path for streamable HTTP
spring.ai.mcp.server.streamable-http.mcp-endpoint=/mcp  // String, default: "/mcp"

// Connection keep-alive interval
spring.ai.mcp.server.streamable-http.keep-alive-interval=  // Duration, default: null (disabled)

// Disallow HTTP DELETE operations
spring.ai.mcp.server.streamable-http.disallow-delete=false  // boolean, default: false

Usage Example:

# Custom streamable HTTP configuration
spring.ai.mcp.server.protocol=STREAMABLE
spring.ai.mcp.server.streamable-http.mcp-endpoint=/api/mcp
spring.ai.mcp.server.streamable-http.keep-alive-interval=15s
spring.ai.mcp.server.streamable-http.disallow-delete=true

With these settings:

MCP endpoint: /api/mcp
Keep-alive sent every 15 seconds
HTTP DELETE operations disabled for security

Configuration Property Types

ApiType Enum

enum ApiType {
    SYNC,   // Synchronous server (blocking operations)
    ASYNC   // Asynchronous server (reactive operations)
}

ServerProtocol Enum

enum ServerProtocol {
    SSE,         // Server-Sent Events (default)
    STREAMABLE,  // Streamable HTTP
    STATELESS    // Stateless Streamable HTTP
}

Configuration Class

The configuration properties are bound to Java classes:

/**
 * Configuration properties for MCP Server
 * Prefix: spring.ai.mcp.server
 */
class McpServerProperties {
    boolean enabled = true;
    boolean stdio = false;
    String name = "mcp-server";
    String version = "1.0.0";
    String instructions = null;
    ApiType type = ApiType.SYNC;
    ServerProtocol protocol = ServerProtocol.SSE;
    Duration requestTimeout = Duration.ofSeconds(20);
    Map<String, String> toolResponseMimeType = new HashMap<>();
    boolean resourceChangeNotification = true;
    boolean toolChangeNotification = true;
    boolean promptChangeNotification = true;
    boolean toolCallbackConverter = true;
    Capabilities capabilities = new Capabilities();

    static class Capabilities {
        boolean resource = true;
        boolean tool = true;
        boolean prompt = true;
        boolean completion = true;
    }
}

/**
 * Configuration properties for MCP Server Annotation Scanner
 * Prefix: spring.ai.mcp.server.annotation-scanner
 */
class McpServerAnnotationScannerProperties {
    boolean enabled = true;
}

Transport Configuration

STDIO Transport

Enable STDIO transport for command-line tools:

spring.ai.mcp.server.stdio=true

The server will communicate via standard input/output streams. No web server is required.

SSE Transport (Default)

Use Server-Sent Events over HTTP:

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

Requires a web starter (Spring MVC or WebFlux).

Streamable HTTP Transport

Use Streamable HTTP protocol:

spring.ai.mcp.server.protocol=STREAMABLE

Requires a web starter (Spring MVC or WebFlux).

Stateless Transport

Use stateless HTTP protocol for scalable deployments:

spring.ai.mcp.server.protocol=STATELESS

Stateless servers do not support bidirectional operations (elicitation, sampling).

Complete Configuration Example

# Server configuration
spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.stdio=false
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.resource=true
spring.ai.mcp.server.capabilities.tool=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

# Tool response MIME types
spring.ai.mcp.server.tool-response-mime-type.generateImage=image/png
spring.ai.mcp.server.tool-response-mime-type.generateDocument=application/pdf

# SSE configuration
spring.ai.mcp.server.sse-endpoint=/api/sse
spring.ai.mcp.server.sse-message-endpoint=/api/mcp/message
spring.ai.mcp.server.base-url=/api/v1
spring.ai.mcp.server.keep-alive-interval=15s

# Annotation scanner
spring.ai.mcp.server.annotation-scanner.enabled=true

# Tool callback converter
spring.ai.mcp.server.tool-callback-converter=true

Environment-Specific Configuration

Use Spring profiles for environment-specific configuration:

# application-dev.properties
spring.ai.mcp.server.stdio=true
spring.ai.mcp.server.name=dev-mcp-server

# 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

Activate with:

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

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

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

configuration.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/reference/

Configuration Properties

Capabilities

Server Properties

Capability Properties

Change Notification Properties

Tool Response MIME Type

Annotation Scanner Properties

Client Configuration Properties

Common Client Properties

STDIO Client Configuration

SSE Client Configuration

Streamable HTTP Client Configuration

SSE Properties

Streamable HTTP Properties

Configuration Property Types

ApiType Enum

ServerProtocol Enum

Configuration Class

Transport Configuration

STDIO Transport

SSE Transport (Default)

Streamable HTTP Transport

Stateless Transport

Complete Configuration Example

Environment-Specific Configuration

configuration.mddocs/reference/