diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index be4e4cf97..1bfbfd5d3 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -241,10 +241,17 @@ public Builder requestBuilder(HttpRequest.Builder requestBuilder) {
 		}
 
 		/**
-		 * Customizes the HTTP client builder.
+		 * Applies the given consumer to the shared {@link HttpRequest.Builder} <b>once,
+		 * at build time</b>. Any headers set here are frozen into the template and
+		 * <b>cannot be updated</b> after the transport is built.
 		 * @param requestCustomizer the consumer to customize the HTTP request builder
 		 * @return this builder
+		 * @deprecated Use
+		 * {@link #requestBuilder(HttpRequest.Builder)} for stable headers, or
+		 * {@link #httpRequestCustomizer(McpSyncHttpClientRequestCustomizer)} /
+		 * {@link #asyncHttpRequestCustomizer(McpAsyncHttpClientRequestCustomizer)} for dynamic per-request customization.
 		 */
+		@Deprecated
 		public Builder customizeRequest(final Consumer<HttpRequest.Builder> requestCustomizer) {
 			Assert.notNull(requestCustomizer, "requestCustomizer must not be null");
 			requestCustomizer.accept(requestBuilder);
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
index 57a27a3fd..8947b38f6 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
@@ -738,10 +738,17 @@ public Builder requestBuilder(HttpRequest.Builder requestBuilder) {
 		}
 
 		/**
-		 * Customizes the HTTP client builder.
+		 * Applies the given consumer to the shared {@link HttpRequest.Builder} <b>once,
+		 * at build time</b>. Any headers set here are frozen into the template and
+		 * <b>cannot be updated</b> after the transport is built.
 		 * @param requestCustomizer the consumer to customize the HTTP request builder
 		 * @return this builder
+		 * @deprecated Use
+		 * {@link #requestBuilder(HttpRequest.Builder)} for stable headers, or
+		 * {@link #httpRequestCustomizer(McpSyncHttpClientRequestCustomizer)} /
+		 * {@link #asyncHttpRequestCustomizer(McpAsyncHttpClientRequestCustomizer)} for dynamic per-request customization.
 		 */
+		@Deprecated
 		public Builder customizeRequest(final Consumer<HttpRequest.Builder> requestCustomizer) {
 			Assert.notNull(requestCustomizer, "requestCustomizer must not be null");
 			requestCustomizer.accept(requestBuilder);