Spring AI MCP Client

Automatically configures and instantiates MCP client beans in Spring Boot applications through convention-over-configuration patterns, eliminating manual bean definition boilerplate. Uses Spring's @EnableAutoConfiguration mechanism to detect MCP client starter on classpath and apply sensible defaults (20s request timeout, SYNC client type, auto-initialization enabled) while allowing override via spring.ai.mcp.client.* properties. Supports both standard JDK HttpClient and WebFlux-based transports, with automatic selection based on which starter dependency is present.

Provides abstracted transport layer supporting STDIO (in-process command execution), SSE (Server-Sent Events over HTTP), and Streamable-HTTP variants, with implementation swapped between standard JDK HttpClient and Spring WebFlux based on starter dependency. Each transport is configured independently via spring.ai.mcp.client.[transport-type].* properties, allowing single application to connect to multiple MCP servers via different transports. STDIO transport executes local commands directly; HTTP transports use streaming to handle long-running MCP operations without blocking.

Provides spring.ai.mcp.client.initialized property (default true) to control whether MCP clients are automatically initialized when created. When true, clients connect to servers immediately; when false, clients are created but not initialized, allowing application to control initialization timing. This enables lazy initialization patterns and deferred connection establishment. Lifecycle hooks (specific hook names not documented) allow applications to react to client initialization events.

Allows configuration of MCP client identity through spring.ai.mcp.client.name (default 'spring-ai-mcp-client') and spring.ai.mcp.client.version (default '1.0.0') properties. These values are sent to MCP servers as part of client initialization, allowing servers to identify and potentially customize behavior based on client identity. Version string enables servers to implement version-specific compatibility logic or feature detection.

Enables configuration of multiple named MCP server connections through either a centralized JSON configuration file (spring.ai.mcp.client.stdio.servers-configuration property) or inline properties map (spring.ai.mcp.client.stdio.connections.[name].command). Each named connection specifies the command to execute (for STDIO) or endpoint URL (for HTTP transports), and can be referenced by name throughout the application. Supports environment variable interpolation and Spring property placeholder syntax, allowing externalized secrets and environment-specific configuration.

Filters which tools exposed by connected MCP servers are made available to Spring AI's tool execution framework, and optionally prefixes tool names to avoid naming collisions when multiple servers expose tools with identical names. Filtering logic is applied during client initialization based on configuration (specific mechanism not detailed in documentation), and prefixing uses customizable prefix generation strategy. This prevents tool namespace pollution and allows applications to selectively enable/disable tools without modifying server configuration.

Integrates MCP client tools with Spring AI's tool execution framework through a callback mechanism (spring.ai.mcp.client.toolcallback.enabled property controls this). When enabled, tools discovered from connected MCP servers are automatically registered as Spring AI ToolCallback implementations, allowing LLMs to invoke them through Spring AI's standard tool-calling APIs. The integration handles marshaling of tool inputs/outputs between Spring AI's type system and MCP protocol format, abstracting transport and serialization details.

Provides annotation-based mechanism (spring.ai.mcp.client.annotation-scanner.enabled controls this) to auto-discover and register MCP client handlers in Spring applications. Annotations allow developers to mark methods or classes as MCP handlers, which are automatically detected during component scanning and registered with the MCP client. This enables declarative, code-first approach to MCP integration without explicit bean configuration. Specific annotation names and handler patterns not documented, but mechanism integrates with Spring's @Component scanning.

Provides both SYNC and ASYNC client implementations (controlled via spring.ai.mcp.client.type property), allowing applications to choose between blocking and non-blocking MCP operations. However, the client type is global — all MCP client instances in an application must use the same type (cannot mix SYNC and ASYNC). SYNC clients block on MCP operations; ASYNC clients return CompletableFuture or reactive types. This constraint simplifies threading model and prevents complex async/sync bridging logic.

Provides configurable request timeout (spring.ai.mcp.client.request-timeout property, default 20 seconds) for all MCP operations, and automatic lifecycle management that cleans up resources when Spring ApplicationContext closes. Timeout applies globally to all MCP operations; individual operation timeouts not supported. Lifecycle management ensures proper shutdown of transport connections and cleanup of thread pools without requiring explicit shutdown code.

Enables root change notifications (spring.ai.mcp.client.root-change-notification property, default true) to receive updates when MCP server's resource roots change. When enabled, client listens for root change events from connected servers and triggers application-level handlers. This allows applications to react to changes in available resources (e.g., new files added to a watched directory) without polling. Notification mechanism and handler registration patterns not documented.

Allows customization of MCP client bean creation through Spring's Customizer pattern (implementing MCP client Customizer interface), enabling post-configuration modifications without overriding auto-configuration. Customizers are applied after auto-configuration creates the client bean, allowing fine-grained control over client properties, transport settings, or handler registration. Multiple customizers can be registered and are applied in order. This pattern integrates with Spring Boot's customization conventions.