Class DefaultMcpClient.Builder

java.lang.Object
dev.langchain4j.mcp.client.DefaultMcpClient.Builder
Enclosing class:
DefaultMcpClient
public static class DefaultMcpClient.Builder extends Object

  • Constructor Details

    • Builder

      public Builder()

  • Method Details

    • transport

      public DefaultMcpClient.Builder transport(McpTransport transport)
      Sets the transport protocol to use for communicating with the MCP server. This is a mandatory parameter. A successfully constructed DefaultMcpClient takes over the resource ownership of this transport and will close it when it itself is closed.

    • key

      public DefaultMcpClient.Builder key(String key)
      Sets a unique identifier for the client. If none is provided, a UUID will be automatically generated.

    • clientName

      public DefaultMcpClient.Builder clientName(String clientName)
      Sets the name that the client will use to identify itself to the MCP server in the initialization message. The default value is "langchain4j".

    • clientVersion

      public DefaultMcpClient.Builder clientVersion(String clientVersion)
      Sets the version string that the client will use to identify itself to the MCP server in the initialization message. The default value is "1.0".

    • protocolVersion

      public DefaultMcpClient.Builder protocolVersion(String protocolVersion)
      Sets the protocol version. If null or empty (the default), the client detects the server's protocol version, preferring 2026-07-28 over 2025-11-25. If explicitly set to "2026-07-28", modern protocol is forced. If set to "2025-11-25", legacy protocol is forced. Any other value triggers detection but uses the given string when advertising the version to the server.

      Detection costs one extra round trip at startup: the client sends server/discover and falls back to the legacy initialize handshake if the server answers with an error or does not answer within protocolDetectionTimeout(Duration). Setting the version explicitly skips the detection round trip entirely, which is also the way out if a server reacts badly to being sent a method it does not know.

    • initializationTimeout

      public DefaultMcpClient.Builder initializationTimeout(Duration initializationTimeout)
      Sets the timeout for initializing the client. The default value is 30 seconds.

    • protocolDetectionTimeout

      public DefaultMcpClient.Builder protocolDetectionTimeout(Duration protocolDetectionTimeout)
      Sets how long the client waits for the server to answer the server/discover request that detects which protocol version the server speaks. A server that does not answer within this time is assumed to speak the legacy protocol, and the client falls back to the initialize handshake.

      This only applies while the protocol version is being detected, which is the case when no explicit protocolVersion(String) is set. It defaults to initializationTimeout(Duration), because a server that is started as a subprocess needs time to boot before it can answer anything, and a detection request that gives up too early makes a modern server look like a legacy one.

      Lower it if your servers answer quickly and you would rather not wait on one that ignores the request instead of rejecting it.

    • toolExecutionTimeout

      public DefaultMcpClient.Builder toolExecutionTimeout(Duration toolExecutionTimeout)
      Sets the timeout for tool execution. This value applies to each tool execution individually. The default value is 60 seconds. A value of zero means no timeout.

    • resourcesTimeout

      public DefaultMcpClient.Builder resourcesTimeout(Duration resourcesTimeout)
      Sets the timeout for resource-related operations (listing resources as well as reading the contents of a resource). The default value is 60 seconds. A value of zero means no timeout.

    • promptsTimeout

      public DefaultMcpClient.Builder promptsTimeout(Duration promptsTimeout)
      Sets the timeout for prompt-related operations (listing prompts as well as rendering the contents of a prompt). The default value is 60 seconds. A value of zero means no timeout.

    • toolExecutionTimeoutErrorMessage

      public DefaultMcpClient.Builder toolExecutionTimeoutErrorMessage(String toolExecutionTimeoutErrorMessage)
      Sets the error message to return when a tool execution times out. The default value is "There was a timeout executing the tool".

    • logHandler

      public DefaultMcpClient.Builder logHandler(McpLogMessageHandler logHandler)
      Sets the log message handler for the client.

    • pingTimeout

      public DefaultMcpClient.Builder pingTimeout(Duration pingTimeout)
      The timeout to apply when waiting for a ping response. Currently, this is only used in the health check - if the server does not send a pong within this timeframe, the health check will fail. The timeout is 10 seconds.

    • reconnectInterval

      public DefaultMcpClient.Builder reconnectInterval(Duration reconnectInterval)
      The delay before attempting to reconnect after a failed connection. The default is 5 seconds.

    • autoHealthCheck

      public DefaultMcpClient.Builder autoHealthCheck(boolean autoHealthCheck)
      Enables or disables the automatic health check feature. When enabled, the client will periodically send ping messages to the server to ensure the connection is alive, and will attempt to reconnect if it's not. The default is enabled

    • autoHealthCheckInterval

      public DefaultMcpClient.Builder autoHealthCheckInterval(Duration interval)
      Sets the interval for the automatic health checks. This is only used when the auto health check feature is enabled. The default is 30 seconds

    • roots

      public DefaultMcpClient.Builder roots(List<McpRoot> roots)
      Specify the initial set of roots that are available to the server upon its request.

    • cacheToolList

      public DefaultMcpClient.Builder cacheToolList(boolean cacheToolList)
      If set to true, the client will cache the tool list obtained from the server until it's notified by the server that the tools have changed or until the cache is evicted. If set to false, there is no tool caching and the client will always fetch the tool list from the server. The default is true.

    • cacheResourceList

      public DefaultMcpClient.Builder cacheResourceList(boolean cacheResourceList)
      If set to true, the client will cache the resource and resource template lists obtained from the server until it's notified by the server that the resources have changed. If set to false, there is no caching and the client will always fetch the resource list from the server. The default is true.

    • cachePromptList

      public DefaultMcpClient.Builder cachePromptList(boolean cachePromptList)
      If set to true, the client will cache the prompt list obtained from the server until it's notified by the server that the prompts have changed. If set to false, there is no caching and the client will always fetch the prompt list from the server. The default is true.

    • listener

      @Deprecated public DefaultMcpClient.Builder listener(McpClientListener listener)
      Deprecated.
      Use addListener(McpClientListener) instead.
      Sets a listener to receive MCP client events. A listener is notified before and after each call to the MCP server. Currently, this applies to tool calls, resource retrievals, and prompt retrievals.

    • addListener

      public DefaultMcpClient.Builder addListener(McpClientListener listener)
      Adds a listener to receive MCP client events. Multiple listeners can be added; they will all be invoked before and after each call to the MCP server. Currently, this applies to tool calls, resource retrievals, and prompt retrievals.

    • addListeners

      public DefaultMcpClient.Builder addListeners(List<McpClientListener> listeners)
      Adds multiple listeners to receive MCP client events. All listeners will be invoked before and after each call to the MCP server. Currently, this applies to tool calls, resource retrievals, and prompt retrievals.

    • progressHandler

      public DefaultMcpClient.Builder progressHandler(McpProgressHandler progressHandler)
      Sets the progress handler for the client. When set, the client will include a progress token in tool execution requests, and progress notifications received from the server will be forwarded to this handler.

    • metaSupplier

      public DefaultMcpClient.Builder metaSupplier(McpMetaSupplier metaSupplier)
      Sets a supplier of _meta fields for MCP client requests and notifications. The supplier is called before every request or notification sent to the server. Unlike HTTP headers, this applies to all transports.

    • toolResultExtractor

      public DefaultMcpClient.Builder toolResultExtractor(McpToolResultExtractor toolResultExtractor)
      Sets the extractor used for MCP tool responses that return ordinary CallToolResult.result.content[] items. Responses with structuredContent are handled separately and are not affected by this setting. The default client only supports structuredContent and text content out of the box. More specialized extraction strategies, such as parsing text items and returning the first JSON object, can be implemented with a custom extractor.

    • onResourceUpdated

      public DefaultMcpClient.Builder onResourceUpdated(BiConsumer<McpClient, String> onResourceUpdated)
      Sets a callback to be invoked when the server sends a notifications/resources/updated notification for a subscribed resource. The callback receives the instance of the affected MCP client and the URI of the updated resource.

    • subscribeToToolListChanges

      public DefaultMcpClient.Builder subscribeToToolListChanges(boolean subscribe)
      Sets whether to automatically subscribe to tool list change notifications when using MCP protocol 2026-07-28 or later. Default is true.

    • subscribeToPromptListChanges

      public DefaultMcpClient.Builder subscribeToPromptListChanges(boolean subscribe)
      Sets whether to automatically subscribe to prompt list change notifications when using MCP protocol 2026-07-28 or later. Default is true.

    • subscribeToResourceListChanges

      public DefaultMcpClient.Builder subscribeToResourceListChanges(boolean subscribe)
      Sets whether to automatically subscribe to resource list change notifications when using MCP protocol 2026-07-28 or later. Default is true.

    • multiRoundTripMaxRetries

      public DefaultMcpClient.Builder multiRoundTripMaxRetries(int multiRoundTripMaxRetries)
      Sets the maximum number of multi round-trip retries for operations that return input_required (MCP protocol 2026-07-28 or later). The default is 3.

    • build

      public DefaultMcpClient build()