Add McpTransportContext to McpSyncClient #522

Kehrlann · 2025-08-27T16:27:19Z

This PR adds McpTransportContext to MCP Clients, and makes it available to (Async|Sync)HttpRequestCustomizers.

Motivation and Context

The motivation is twofold:

It creates a unified API for reading the "context" in which an MCP Client request is issued, regardless of sync/async. It can be consumed by HttpClient-based transports through HttpRequestCustomizer, or through the reactor context in WebClient-based transports.
It also addresses limitations with thread local usage in request customizers, see TransportContext for Client side #479

How Has This Been Tested?

Test with Spring AI + Spring Security for passing JWT tokens to MCP Sync clients.

Breaking Changes

Following the move of (Async|Sync)HttpRequestCustomizer to Mcp(Async|Sync)HttpRequestCustomizer, itself a breaking change, I also changed the signatures of those classes.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

chemicL

Great progress! Left some comments after our sync discussion :)

chemicL · 2025-08-29T11:50:55Z

mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java


+import io.modelcontextprotocol.server.McpTransportContext;


Let's move McpTransportContext up a level into a new common package. It will be a breaking change, but it's a super recent type.

chemicL · 2025-08-29T12:06:21Z

mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java

@@ -183,6 +185,8 @@ class SyncSpec {

 		private Function<ElicitRequest, ElicitResult> elicitationHandler;

+		private Supplier<McpTransportContext> contextProvider = McpTransportContext.EMPTY::copy;


We don't need to copy here. We should ensure that the copy is made whenever there is an intention for the user to modify the context, e.g. when creating an empty one that is being filled in and used as the provided result.

A couple of ideas:

Hide DefaultMcpTransportContext (currently it's public, let's make it package private)

Add factory methods to McpTransportContext: empty() which returns the immutable instance; and create() which creates an empty but mutable container.

Another note on the McpTransportContext:

We use it already on the server side, where the extractor expects a mutable instance that it can fill in.
With the client we have the opposite where the provider creates an instance and expects to mutate it.

On the read side, however we have the user handlers in server specification that are only supposed to read contents and we should ensure that mutations are not allowed because there is no use of mutating the contents.

On the client end, the customizer is the reader also so it should be disallowed to write something to the context.

Therefore, perhaps let's break the API a little bit:

McpTransportContext#put is removed! The McpTransportContext is just a container of immutable context

McpTransportExtractor - deprecate McpTransportContext extract(T request, McpTransportContext transportContext) or even remove it (BREAKING) and just have McpTransportContext extract(T request) that allows to call McpTransportContext.create(Map) which would accept a Map that is already populated and now the McpTransportContext is only the view.

Client's transport context provider is also creating an instance like the extractor.

Customizer is just supposed to read values using get(K).

chemicL · 2025-08-29T13:00:21Z

...n/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpRequestCustomizer.java

- * Streamable HTTP transport.
+ * Streamable HTTP transport. Do not rely on thread-locals in this implementation, instead
+ * use {@link SyncSpec#transportContextProvider} to extract context, and then consume it
+ * through {@link McpTransportContext}.
 *
 * @author Daniel Garnier-Moiroux
 */
 public interface McpSyncHttpRequestCustomizer {


Why not rename it to McpSyncHttpClientRequestCustomizer to reflect that it is tied to JDK's HttpClient.

chemicL · 2025-08-29T13:20:20Z

mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java

+		 * @param contextProvider A supplier to create a context
+		 * @return This builder for method chaining
+		 */
+		public SyncSpec transportContextProvider(Supplier<McpTransportContext> contextProvider) {


Let's perhaps add a comment so users are not too confused by the lack of this method on the AsyncSpec to clarify that the means to achieve the same is to simply append a contextWrite(McpTransportContext.KEY, context) to any McpAsyncClient API call.

chemicL · 2025-08-29T13:22:21Z

mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java

@@ -177,36 +185,43 @@ public boolean closeGracefully() {
 	public McpSchema.InitializeResult initialize() {
 		// TODO: block takes no argument here as we assume the async client is
 		// configured with a requestTimeout at all times
-		return this.delegate.initialize().block();
+		var context = this.contextProvider.get();
+		return this.delegate.initialize().contextWrite(ctx -> ctx.put(McpTransportContext.KEY, context)).block();


How about adding a method like Mono<?> withProvidedContext(...) that wraps all the calls and attaches .contextWrite(ctx -> ctx.put(McpTransportContext.KEY, this.contextProvider.get())

chemicL · 2025-08-29T13:31:13Z

...rc/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java

@@ -247,7 +250,9 @@ private Mono<Disposable> reconnect(McpTransportStream<Disposable> stream) {
 					.header("Cache-Control", "no-cache")
 					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 					.GET();
-				return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, null));
+				var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);


Let's perhaps use the innermost Context to be super certain that if at any point we alter the inner chain we do still grab the correct reference here. Replacing Mono.defer on line 236 with Mono.deferContextual(connectionCtx -> { should do the trick.

chemicL · 2025-08-29T13:32:46Z

mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java

+				mcpSyncClient -> {
+					mcpSyncClient.initialize();
+
+					var transportCaptor = ArgumentCaptor.forClass(McpTransportContext.class);


Hmm, perhaps we can add equality overrides to DefaultMcpTransportContext? :)

- McpSyncClient should be considered thread-agnostic, and therefore consumers cannot rely on thread locals to propagate "context", e.g. pass down the Servlet request reference in a server context. - This PR introduces a mechanism for populating an McpTransportContext before executing client operations, and reworks the HTTP request customizers to leverage that McpTransportContext. - This introduces a breaking change to the Sync/Async request customizers. Signed-off-by: Daniel Garnier-Moiroux <[email protected]>

Signed-off-by: Daniel Garnier-Moiroux <[email protected]>

Kehrlann · 2025-08-29T18:43:21Z

@chemicL @tzolov I have applied the requested changes.

Kehrlann force-pushed the dgarnier/client-mcptransportcontext branch 8 times, most recently from 15bb3f9 to 703d363 Compare August 29, 2025 09:47

Kehrlann changed the title ~~DRAFT: Add McpTransportContext in clients~~ Add McpTransportContext to McpSyncClient Aug 29, 2025

Kehrlann force-pushed the dgarnier/client-mcptransportcontext branch from 703d363 to 4f7a937 Compare August 29, 2025 10:02

Kehrlann marked this pull request as ready for review August 29, 2025 10:17

tzolov added this to the 0.12.0 milestone Aug 29, 2025

chemicL requested changes Aug 29, 2025

View reviewed changes

Kehrlann force-pushed the dgarnier/client-mcptransportcontext branch from 4f7a937 to 477fbd6 Compare August 29, 2025 14:59

Kehrlann added 3 commits August 29, 2025 20:42

Move McpTransportContext to common package, make impl immutable

c2ed1b7

Signed-off-by: Daniel Garnier-Moiroux <[email protected]>

Rename *HttpRequestCustomizer -> *HttpClientRequestCustomizer

98eb323

Signed-off-by: Daniel Garnier-Moiroux <[email protected]>

Kehrlann force-pushed the dgarnier/client-mcptransportcontext branch from 477fbd6 to 98eb323 Compare August 29, 2025 18:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add McpTransportContext to McpSyncClient #522

Add McpTransportContext to McpSyncClient #522

Kehrlann commented Aug 27, 2025 •

edited

Loading

Uh oh!

chemicL left a comment

Uh oh!

chemicL Aug 29, 2025

Uh oh!

chemicL Aug 29, 2025

Uh oh!

chemicL Aug 29, 2025

Uh oh!

chemicL Aug 29, 2025

Uh oh!

chemicL Aug 29, 2025

Uh oh!

chemicL Aug 29, 2025

Uh oh!

chemicL Aug 29, 2025

Uh oh!

chemicL Aug 29, 2025

Uh oh!

Kehrlann commented Aug 29, 2025

Uh oh!

Uh oh!

		@@ -183,6 +185,8 @@ class SyncSpec {

		private Function<ElicitRequest, ElicitResult> elicitationHandler;

		private Supplier<McpTransportContext> contextProvider = McpTransportContext.EMPTY::copy;


		import io.modelcontextprotocol.server.McpTransportContext;

Add McpTransportContext to McpSyncClient #522

Are you sure you want to change the base?

Add McpTransportContext to McpSyncClient #522

Conversation

Kehrlann commented Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

chemicL left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kehrlann commented Aug 29, 2025

Uh oh!

Uh oh!

Kehrlann commented Aug 27, 2025 •

edited

Loading