Class McpClientModernAutoConfiguration

java.lang.Object
org.springframework.ai.mcp.client.common.autoconfigure.McpClientModernAutoConfiguration

@AutoConfiguration @ConditionalOnClass(io.modelcontextprotocol.modern.client.McpClient.class) @EnableConfigurationProperties({McpClientCommonProperties.class,McpClientModernProperties.class,McpStreamableHttpClientProperties.class}) @ConditionalOnProperty(prefix="spring.ai.mcp.client", name="enabled", havingValue="true", matchIfMissing=true) public class McpClientModernAutoConfiguration extends Object
Auto-configuration of the MCP client connections that speak the 2026-07-28 ("modern") protocol revision. A connection is modern when its protocol property is MODERN, for example spring.ai.mcp.client.streamable-http.connections.tickets.protocol=MODERN. Connections without that property stay on the legacy protocol, so an application can talk to legacy and modern servers at the same time.

It creates three kinds of beans, the first two being the modern counterparts of the legacy transports and clients:

A tool listing is kept for as long as the server allows when the server marks it as public. A listing the server marks as private is kept only by a client that outlives a request: the one of a connection with client-scope=SHARED, which is meant for an application that calls the server under a single identity, or a client that the scope bean of a connection with client-scope=CUSTOM keeps.

McpToolCallbackAutoConfiguration adds the tools of these connections to the SyncMcpToolCallbackProvider or AsyncMcpToolCallbackProvider bean, next to the tools of the legacy clients, so the application keeps injecting a single ToolCallbackProvider.

Modern clients are created without contacting the server, so nothing is sent at startup and spring.ai.mcp.client.initialized does not apply to them.

With the asynchronous client type the tools are listed and called through the asynchronous client of the SDK, which holds no caller: an AsyncModernMcpTransportContextProvider bean supplies the caller of each request. The reactive methods serve the asynchronous connections: those that return a Mono.

The @McpElicitation and @McpProgress methods that name a modern connection in their clients attribute answer the elicitation requests and receive the progress of that connection, as they do for a legacy connection. A method may take the schema types of either protocol, and a ToolContext to receive the tool context of the tool call it serves. The @McpToolListChanged, @McpPromptListChanged and @McpResourceListChanged methods are called for a connection that sets listen=true. @McpSampling and @McpLogging are not supported for modern connections, and a warning is logged for them.

Customization points:

  • McpClientCustomizer<HttpClientMcpTransport.Builder> beans customize a transport;
  • McpHttpRequestCustomizer beans and a McpHttpAuthorizationErrorHandler bean are added to every transport, for example to send an access token;
  • McpClientCustomizer<McpClient.SyncBuilder> beans customize a client, for example to set its transportContextProvider. With the default PER_REQUEST client scope they run for each new client, on the thread that resolves the tools. A handler set by a customizer is used for the connections that no annotated handler method names; for the tool calls of the others the annotated methods take precedence.
  • A SyncModernMcpClientScope bean selects the client of each request of the connections with client-scope=CUSTOM, for example to keep one for each user;
  • SyncModernMcpChangeListener beans hear about the changes that the servers of the listening connections report.
  • SyncModernMcpToolCallCustomizer beans customize each tool call, with the ToolContext of that call. They run after the annotated handlers are set for the call, so they can replace them.
  • With the asynchronous client type the counterparts apply: McpClientCustomizer<McpClient.AsyncBuilder>, AsyncModernMcpClientScope and AsyncModernMcpToolCallCustomizer beans.
Since:
2.1.0
Author:
Christian Tzolov
  • Constructor Details

    • McpClientModernAutoConfiguration

      public McpClientModernAutoConfiguration()
  • Method Details

    • modernStreamableHttpTransports

      @Bean public List<NamedModernClientMcpTransport> modernStreamableHttpTransports(McpStreamableHttpClientProperties streamableProperties, org.springframework.beans.factory.ObjectProvider<tools.jackson.databind.json.JsonMapper> jsonMapperProvider, org.springframework.beans.factory.ObjectProvider<io.modelcontextprotocol.modern.client.transport.McpHttpRequestCustomizer> requestCustomizers, org.springframework.beans.factory.ObjectProvider<io.modelcontextprotocol.modern.client.transport.McpHttpAuthorizationErrorHandler> authorizationErrorHandler, org.springframework.beans.factory.ObjectProvider<McpClientCustomizer<io.modelcontextprotocol.modern.client.transport.HttpClientMcpTransport.Builder>> transportCustomizers)
      Creates a transport on the JDK HttpClient for each modern Streamable HTTP connection.
      Parameters:
      streamableProperties - the configured connections
      jsonMapperProvider - the JSON mapper of the application, if any
      requestCustomizers - the customizers that add headers to each HTTP request
      authorizationErrorHandler - the handler of 401 and 403 answers, if any
      transportCustomizers - the customizers of the transport builders
      Returns:
      the named transports
    • modernMcpSyncConnections

      @Bean @ConditionalOnProperty(prefix="spring.ai.mcp.client", name="type", havingValue="SYNC", matchIfMissing=true) public List<SyncModernMcpConnection> modernMcpSyncConnections(org.springframework.beans.factory.ObjectProvider<List<NamedModernClientMcpTransport>> transportsProvider, McpStreamableHttpClientProperties streamableProperties, McpClientCommonProperties commonProperties, McpClientModernProperties modernProperties, org.springframework.beans.factory.ObjectProvider<McpClientCustomizer<io.modelcontextprotocol.modern.client.McpClient.SyncBuilder>> clientCustomizers, org.springframework.beans.factory.ObjectProvider<ClientMcpSyncHandlersRegistry> handlersRegistry, org.springframework.beans.factory.ObjectProvider<SyncModernMcpClientScope> clientScopeProvider)
      Creates a connection for each named transport. All clients of a connection share its transport. The client scope is read from the configured connection of the same name, so a transport contributed by the application without such a connection gets a client for each request.
      Parameters:
      transportsProvider - the named transports, auto-configured or contributed by the application
      streamableProperties - the configured connections
      commonProperties - the common MCP client properties
      modernProperties - the modern MCP client properties
      clientCustomizers - the customizers of the client builders
      handlersRegistry - the registry of the annotated client handler methods, if the annotation scanner is enabled
      clientScopeProvider - the bean that selects the clients of the connections with the CUSTOM client scope, which must be defined if there is such a connection
      Returns:
      the connections
    • modernMcpAsyncConnections

      @Bean @ConditionalOnProperty(prefix="spring.ai.mcp.client", name="type", havingValue="ASYNC") public List<AsyncModernMcpConnection> modernMcpAsyncConnections(org.springframework.beans.factory.ObjectProvider<List<NamedModernClientMcpTransport>> transportsProvider, McpStreamableHttpClientProperties streamableProperties, McpClientCommonProperties commonProperties, McpClientModernProperties modernProperties, org.springframework.beans.factory.ObjectProvider<McpClientCustomizer<io.modelcontextprotocol.modern.client.McpClient.AsyncBuilder>> clientCustomizers, org.springframework.beans.factory.ObjectProvider<AsyncModernMcpClientScope> clientScopeProvider, org.springframework.beans.factory.ObjectProvider<AsyncModernMcpTransportContextProvider> transportContextProvider, org.springframework.beans.factory.ObjectProvider<ClientMcpAsyncHandlersRegistry> handlersRegistry)
      Creates an asynchronous connection for each named transport, with the ASYNC client type. All clients of a connection share its transport. The client scope is read from the configured connection of the same name, so a transport contributed by the application without such a connection gets a client for each request.

      An asynchronous client holds no caller. The caller of a request is supplied by the AsyncModernMcpTransportContextProvider bean, if there is one, on the thread that resolves the tools.

      Parameters:
      transportsProvider - the named transports, auto-configured or contributed by the application
      streamableProperties - the configured connections
      commonProperties - the common MCP client properties
      modernProperties - the modern MCP client properties
      clientCustomizers - the customizers of the client builders
      clientScopeProvider - the bean that selects the clients of the connections with the CUSTOM client scope, which must be defined if there is such a connection
      transportContextProvider - the bean that supplies the caller of a request
      handlersRegistry - the registry of the annotated client handler methods, if the annotation scanner is enabled
      Returns:
      the connections
    • modernMcpChangeSubscriber

      @Bean @ConditionalOnMissingBean @ConditionalOnProperty(prefix="spring.ai.mcp.client", name="type", havingValue="SYNC", matchIfMissing=true) public SyncModernMcpChangeSubscriber modernMcpChangeSubscriber(org.springframework.beans.factory.ObjectProvider<List<SyncModernMcpConnection>> connectionsProvider, McpStreamableHttpClientProperties streamableProperties, McpClientModernProperties modernProperties, org.springframework.beans.factory.ObjectProvider<SyncModernMcpChangeListener> changeListeners, org.springframework.beans.factory.ObjectProvider<ClientMcpSyncHandlersRegistry> handlersRegistry)
      Creates the subscriber that keeps a listen stream open to the server of each modern connection that sets listen=true. It opens the streams when the application has started, without waiting for the servers. A stream that ended is opened again after one second, and after pauses that double up to the unreachable cool-down time for as long as that fails. A stream is opened by a client of its own, outside of any request, so it carries the identity of the application and not that of a caller.
      Parameters:
      connectionsProvider - the modern connections
      streamableProperties - the configured connections
      modernProperties - the modern MCP client properties
      changeListeners - the listeners of the application, which hear about what the servers report next to the tool callback provider
      handlersRegistry - the registry of the annotated client handler methods, if the annotation scanner is enabled; a stream also listens for the changes of the prompts and resources if a list-changed method wants to hear about them
      Returns:
      the subscriber, which listens to no server if no connection asks for it
    • modernMcpAsyncChangeSubscriber

      @Bean @ConditionalOnMissingBean @ConditionalOnProperty(prefix="spring.ai.mcp.client", name="type", havingValue="ASYNC") public AsyncModernMcpChangeSubscriber modernMcpAsyncChangeSubscriber(org.springframework.beans.factory.ObjectProvider<List<AsyncModernMcpConnection>> connectionsProvider, McpStreamableHttpClientProperties streamableProperties, McpClientModernProperties modernProperties, org.springframework.beans.factory.ObjectProvider<AsyncModernMcpChangeListener> changeListeners, org.springframework.beans.factory.ObjectProvider<ClientMcpAsyncHandlersRegistry> handlersRegistry)
      Parameters:
      connectionsProvider - the modern connections
      streamableProperties - the configured connections
      modernProperties - the modern MCP client properties
      changeListeners - the listeners of the application, which hear about what the servers report next to the tool callback provider
      handlersRegistry - the registry of the annotated client handler methods, if the annotation scanner is enabled; a stream also listens for the changes of the prompts and resources if a reactive list-changed method wants to hear about them
      Returns:
      the subscriber, which listens to no server if no connection asks for it