Class StreamableHttpMcpTransport.Builder

java.lang.Object
dev.langchain4j.mcp.client.transport.http.StreamableHttpMcpTransport.Builder
Enclosing class:
StreamableHttpMcpTransport

public static class StreamableHttpMcpTransport.Builder extends Object
  • Constructor Details

    • Builder

      public Builder()
  • Method Details

    • httpClientBuilder

      @Experimental public StreamableHttpMcpTransport.Builder httpClientBuilder(HttpClientBuilder httpClientBuilder)
      Supplies the HTTP backend used for all requests, including the subsidiary SSE channel. The client must implement HttpClient.stream(HttpRequest, ServerSentEventParser) and honor subscription cancellation; otherwise every request fails. Without a custom builder or client, the transport uses the JDK HTTP client when it is on the classpath, even if other HTTP clients are on the classpath too. It uses another client only when the langchain4j.http.clientBuilderFactory system property names it, or when the JDK client is excluded from the classpath. HttpClientBuilderLoader then selects the client.

      The transport owns the client it builds and closes it on StreamableHttpMcpTransport.close() if it implements AutoCloseable; clients that do not implement it are not closed. Use httpClient(HttpClient) to supply a caller-owned, shared client instead. Configure TLS, HTTP version and redirects on the supplied builder instead of using the corresponding transport options. Cannot be combined with httpClient. An explicit transport timeout(Duration) is set as the connection timeout on the supplied builder; otherwise the supplied backend retains its connection timeout settings and defaults. The 60-second default applies only when no builder or client is supplied.

      The transport does not override the backend's read timeout, and MCP responses and SSE streams can stay idle for a long time. Some backends have a short default read timeout (10 seconds for OkHttp), so disable or raise it. Some backends follow redirects by default (OkHttp, Apache), which can send custom headers and the request body to another host; disable redirects on the backend if not needed.

      Parameters:
      httpClientBuilder - the HTTP client builder
      Returns:
      this builder
      Since:
      1.23.0
    • httpClient

      Supplies a caller-owned HTTP client, which may be shared by several transports. The client must support the same streaming API as httpClientBuilder(HttpClientBuilder). Closing this transport cancels its exchanges but does not close this client. Configure connection timeout, TLS, HTTP version and redirects before supplying the client; the corresponding transport options cannot be combined with this method. Cannot be combined with httpClientBuilder. The backend's read timeout and redirect settings apply, see httpClientBuilder(HttpClientBuilder).
      Parameters:
      httpClient - the HTTP client
      Returns:
      this builder
      Since:
      1.23.0
    • url

      The URL of the MCP server.
    • customHeaders

      public StreamableHttpMcpTransport.Builder customHeaders(Map<String,String> customHeaders)
      The request headers of the MCP server.
    • customHeaders

      public StreamableHttpMcpTransport.Builder customHeaders(Supplier<Map<String,String>> customHeadersSupplier)
      A supplier for dynamic request headers of the MCP server. The supplier is called for each request, allowing headers to be updated dynamically.
    • customHeaders

      public StreamableHttpMcpTransport.Builder customHeaders(McpHeadersSupplier customHeadersSupplier)
      A supplier for dynamic request headers of the MCP server. The supplier is called for each request, allowing headers to be updated dynamically.
    • timeout

      public StreamableHttpMcpTransport.Builder timeout(Duration timeout)
      The connection timeout (applied on the http client level). Application-level timeouts are handled by the MCP client itself. Cannot be combined with httpClient(HttpClient); configure it on the HTTP client instead.
    • logRequests

      public StreamableHttpMcpTransport.Builder logRequests(boolean logRequests)
      Whether to log all requests that are sent over this transport.
    • logResponses

      public StreamableHttpMcpTransport.Builder logResponses(boolean logResponses)
      Whether to log all responses received over this transport.
    • logger

      public StreamableHttpMcpTransport.Builder logger(org.slf4j.Logger logger)
      Sets a custom Logger to be used for traffic logging (both requests and responses). This logger will be used for both regular HTTP responses and Server-Sent Events (SSE) traffic. If not specified, a default logger will be used.
      Parameters:
      logger - an alternate Logger to be used instead of the default one provided by Langchain4J for traffic logging.
      Returns:
      this.
    • executor

      public StreamableHttpMcpTransport.Builder executor(Executor executor)
      An optional Executor that will be used for executing requests and handling responses. It will also be used for scheduling auto-reconnect attempts of the subsidiary SSE channel if that is enabled. Responses are handled on this executor also with httpClientBuilder(HttpClientBuilder) or httpClient(HttpClient); the HTTP client itself still sends requests on its own threads. If not provided, a default shared executor is used for reconnects and responses are handled on the HTTP client's threads.
    • sslContext

      public StreamableHttpMcpTransport.Builder sslContext(SSLContext sslContext)
      Supplies a custom SSLContext used when establishing HTTPS connections to the MCP server, allowing private CAs or certificates. Works only with the JDK HTTP client. Cannot be combined with httpClientBuilder(HttpClientBuilder) or httpClient(HttpClient); configure it on the HTTP client instead.
    • setHttpVersion1_1

      public StreamableHttpMcpTransport.Builder setHttpVersion1_1()
      Forces the transport to use HTTP/1.1 instead of the default HTTP/2. Works only with the JDK HTTP client. Cannot be combined with httpClientBuilder(HttpClientBuilder) or httpClient(HttpClient); configure it on the HTTP client instead.
    • followRedirects

      public StreamableHttpMcpTransport.Builder followRedirects(boolean followRedirects)
      Enables or disables following HTTP redirects (3xx status codes). When enabled, the transport will automatically follow redirects using HttpClient.Redirect.NORMAL policy (always redirect, except from HTTPS to HTTP). Defaults to false. Enabling it works only with the JDK HTTP client, and cannot be combined with httpClientBuilder(HttpClientBuilder) or httpClient(HttpClient); configure redirects on the HTTP client instead.
    • subsidiaryChannel

      public StreamableHttpMcpTransport.Builder subsidiaryChannel(boolean subsidiaryChannelEnabled)
      Enables or disables the subsidiary SSE channel. When enabled, the transport will open an HTTP GET-based SSE stream after initialization, allowing the server to send notifications and requests to the client without the client first sending data via HTTP POST. If the server does not support the subsidiary channel (returns 405), the transport will log a warning and continue without it. If the stream breaks after being successfully established, the transport will automatically attempt to reconnect. Only used with the legacy MCP protocol (versions up to 2025-11-25). In modern protocol, notifications are received via subscriptions/listen. Defaults to false.
    • maxMessageSize

      public StreamableHttpMcpTransport.Builder maxMessageSize(Integer maxMessageSize)
      The maximum size, in bytes, of a single message received from the server: the data of one event on an SSE stream, or the whole body of any other response, such as a JSON response. This applies to every response, including the subsidiary SSE channel. When a server sends a larger message, the transport closes the stream: a pending request fails and the subsidiary channel reconnects. This protects the client against servers that send an endless or huge message, which would otherwise be buffered in memory until it runs out. The size is that of the JSON text, so binary content such as images, which is base64-encoded, takes about a third more than its raw size. Defaults to 20 MiB.
      Parameters:
      maxMessageSize - the maximum message size in bytes, must be greater than zero; null means the default
      Returns:
      this builder
      Since:
      1.24.0
    • build