Deprecate Builder.customizeRequest() in favor of httpRequestCustomizer() #788

Bug description

Builder.customizeRequest() in both HttpClientSseClientTransport and HttpClientStreamableHttpTransport executes its consumer once at build time, mutating the shared requestBuilder. Any headers set here (e.g., Authorization) are frozen into the template and copied to every subsequent request via requestBuilder.copy(). They cannot be updated after the transport is built.

This becomes a significant issue for OAuth token refresh scenarios: after refreshing an access token, the transport continues sending the old expired token because the header was baked into the request builder at construction time.

The method name customizeRequest strongly suggests per-request behavior, making it easy to use incorrectly. The correct alternatives — httpRequestCustomizer() and asyncHttpRequestCustomizer() — already exist and run on every request, but there's no deprecation notice guiding users toward them.

Environment

MCP Java SDK (latest main branch). Affects both HttpClientSseClientTransport and HttpClientStreamableHttpTransport.

Steps to reproduce

var transport = HttpClientSseClientTransport.builder(baseUri)
    .customizeRequest(builder -> {
        // This runs ONCE at build time — token is frozen
        builder.header("Authorization", "Bearer " + tokenProvider.getAccessToken());
    })
    .build();

// Later: token expires, tokenProvider returns a new token
// But all requests still carry the old token from build time

Expected behavior

Users should be guided toward httpRequestCustomizer() or asyncHttpRequestCustomizer() for dynamic headers. Ideally, customizeRequest() should be marked @Deprecated with clear Javadoc explaining the build-time-only semantics.

Real-world impact

We encountered this in production where our MCP connector's OAuth token refresh was completely non-functional:

1. Access token expires → server returns 401
2. Connector successfully refreshes the token (new token stored)
3. Connector retries with the same transport (no re-creation, since McpAsyncClient is already initialized)
4. But requestBuilder still has the old token baked in from build time
5. Retry sends the old expired token → 401 again → permanent failure

Switching from customizeRequest() to httpRequestCustomizer() resolved the issue.

Additional note

The current Javadoc for customizeRequest() says "Customizes the HTTP client builder" which is also slightly misleading — it customizes the request builder, not the client builder (that's customizeClient()).

A PR with the deprecation annotation and updated Javadoc has been submitted: #791