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

Client Customizers

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

Customizer interfaces for configuring MCP client connections. These interfaces allow fine-grained control over client initialization and behavior.

Capabilities

McpSyncClientCustomizer

Customizes synchronous MCP client configurations before connection initialization.

/**
 * Customizes synchronous MCP client specifications
 */
@FunctionalInterface
interface McpSyncClientCustomizer {
    /**
     * Customize the MCP client specification
     * @param name The connection name
     * @param spec The client specification builder
     */
    void customize(String name, McpClient.SyncSpec spec);
}

Usage Example:

import org.springframework.ai.mcp.customizer.McpSyncClientCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ClientCustomizerConfig {

    @Bean
    public McpSyncClientCustomizer connectionTimeoutCustomizer() {
        return (name, spec) -> {
            // Customize connection timeout
            spec.requestTimeout(Duration.ofSeconds(30));
        };
    }

    @Bean
    public McpSyncClientCustomizer loggingCustomizer() {
        return (name, spec) -> {
            // Enable detailed logging for specific connections
            if ("production-server".equals(name)) {
                spec.enableLogging(true);
            }
        };
    }

    @Bean
    public McpSyncClientCustomizer metadataCustomizer() {
        return (name, spec) -> {
            // Add custom metadata to client info
            spec.clientInfo(info -> info
                .name("my-app")
                .version("1.0.0")
            );
        };
    }
}

Customization Options:

Sync client specifications support customization of:

Request timeout
Client information (name, version)
Logging configuration
Transport settings
Error handling behavior
Retry policies

McpAsyncClientCustomizer

Customizes asynchronous (reactive) MCP client configurations.

/**
 * Customizes asynchronous MCP client specifications
 */
@FunctionalInterface
interface McpAsyncClientCustomizer {
    /**
     * Customize the async MCP client specification
     * @param name The connection name
     * @param spec The async client specification builder
     */
    void customize(String name, McpClient.AsyncSpec spec);
}

Usage Example:

@Configuration
public class AsyncCustomizerConfig {

    @Bean
    public McpAsyncClientCustomizer reactiveTimeoutCustomizer() {
        return (name, spec) -> {
            // Configure reactive timeouts
            spec.requestTimeout(Duration.ofSeconds(45));
        };
    }

    @Bean
    public McpAsyncClientCustomizer backpressureCustomizer() {
        return (name, spec) -> {
            // Configure backpressure strategy for reactive streams
            spec.maxConcurrency(100);
            spec.bufferSize(256);
        };
    }

    @Bean
    public McpAsyncClientCustomizer connectionCustomizer() {
        return (name, spec) -> {
            // Customize connection parameters per server
            switch (name) {
                case "fast-server":
                    spec.requestTimeout(Duration.ofSeconds(10));
                    break;
                case "slow-server":
                    spec.requestTimeout(Duration.ofSeconds(120));
                    break;
                default:
                    spec.requestTimeout(Duration.ofSeconds(30));
            }
        };
    }
}

Customization Options:

Async client specifications support customization of:

Request timeout
Reactive backpressure settings
Client information
Transport settings
Connection pooling
Error handling strategies

Using Multiple Customizers

Spring automatically applies all registered customizers to client specifications. Customizers are applied in the order they are registered.

@Configuration
public class MultipleCustomizersConfig {

    @Bean
    public McpSyncClientCustomizer timeoutCustomizer() {
        return (name, spec) -> spec.requestTimeout(Duration.ofSeconds(30));
    }

    @Bean
    public McpSyncClientCustomizer loggingCustomizer() {
        return (name, spec) -> spec.enableLogging(true);
    }

    @Bean
    public McpSyncClientCustomizer securityCustomizer() {
        return (name, spec) -> {
            // Add security headers or authentication
            spec.addHeader("X-API-Key", getApiKey(name));
        };
    }
}

Conditional Customization

Customizers can apply different configurations based on connection name, environment, or other factors:

@Configuration
public class ConditionalCustomizerConfig {

    @Value("${spring.profiles.active}")
    private String activeProfile;

    @Bean
    public McpSyncClientCustomizer environmentAwareCustomizer() {
        return (name, spec) -> {
            if ("production".equals(activeProfile)) {
                // Production settings
                spec.requestTimeout(Duration.ofSeconds(60));
                spec.enableRetry(true);
                spec.maxRetries(3);
            } else {
                // Development settings
                spec.requestTimeout(Duration.ofSeconds(10));
                spec.enableLogging(true);
            }
        };
    }

    @Bean
    public McpSyncClientCustomizer serverSpecificCustomizer() {
        return (name, spec) -> {
            // Different settings per server
            if (name.startsWith("critical-")) {
                spec.requestTimeout(Duration.ofSeconds(120));
                spec.enableRetry(true);
            } else if (name.startsWith("cache-")) {
                spec.requestTimeout(Duration.ofSeconds(5));
                spec.enableRetry(false);
            }
        };
    }
}

Client Specification API

The McpClient.SyncSpec and McpClient.AsyncSpec builders provide the following configuration methods (exact API may vary):

/**
 * Common configuration methods for client specifications
 */
interface ClientSpec {
    /**
     * Set request timeout
     */
    ClientSpec requestTimeout(Duration timeout);

    /**
     * Configure client information
     */
    ClientSpec clientInfo(Consumer<Implementation.Builder> configurer);

    /**
     * Enable or disable logging
     */
    ClientSpec enableLogging(boolean enabled);

    /**
     * Enable or disable retry on failure
     */
    ClientSpec enableRetry(boolean enabled);

    /**
     * Set maximum retry attempts
     */
    ClientSpec maxRetries(int maxRetries);

    /**
     * Add custom header to requests
     */
    ClientSpec addHeader(String name, String value);
}

Note: Consult the MCP Java SDK documentation for the complete list of configuration options available on client specifications.

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